การโทร

สร้างการโทรbeta

ฟีเจอร์นี้อยู่ในช่วงทดสอบแบบปิด โปรดติดต่อฝ่ายสนับสนุนด้านเทคนิคเพื่อขอเปิดสิทธิ์ให้เวิร์กสเปซ

ขณะนี้รองรับเฉพาะการโทรเสียงและวิดีโอแบบตัวต่อตัวผ่าน WhatsApp เท่านั้น เตรียม join_url ส่วนตัวที่ใช้ได้ครั้งเดียว เปิดลิงก์แล้วกด Start call เพื่อเริ่มโทร

POSThttps://api.unifyport.ai/v1/calls

ช่องทางที่รองรับ

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ตรวจว่าเวิร์กสเปซได้รับสิทธิ์ทดสอบแบบปิด ก่อนสร้างการโทร ให้ยืนยันตัวตน WhatsApp จนเสร็จและตรวจ runtime_status=running ใช้ conversation_id ของบทสนทนาส่วนตัวภายใต้บัญชีนี้

การเริ่มโทรในเบราว์เซอร์ต้องอนุญาตไมโครโฟน ส่วนสิทธิ์กล้องเป็นตัวเลือก

ที่มาของพารามิเตอร์

account_id: รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี
to.id · to.type: ใช้ conversation_id ที่ API ส่งกลับของบทสนทนาส่วนตัวเป้าหมายภายใต้บัญชีนี้ใน to.id โดยไม่แก้ไข และตั้ง to.type=user ห้ามแทนด้วยสตริงหมายเลขโทรศัพท์ รายละเอียดบทสนทนา

คำขอ

curl -X POST 'https://api.unifyport.ai/v1/calls' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}'

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key

stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

Content-Type

stringจำเป็น

ใช้ application/json เมื่อต้องส่งเนื้อหาของคำขอเป็น JSON

เนื้อหาของคำขอ

account_id

stringจำเป็น

ID บัญชีในเวิร์กสเปซปัจจุบัน

pattern: ^acc_[A-Za-z0-9][A-Za-z0-9_-]*$

to

objectจำเป็น

ผู้รับสายแบบตัวต่อตัว

id

stringจำเป็น

ระบุ conversation_id ของบทสนทนาเป้าหมายภายใต้บัญชีปัจจุบัน โดยใช้ค่าที่ API ส่งกลับโดยไม่แก้ไข

minLength: 1

type

stringจำเป็น

รองรับเฉพาะ user ส่วน group/channel จะได้รับข้อผิดพลาดว่าไม่รองรับ

enum: user, group, channel

media_type

stringจำเป็น

voice คือเสียง ส่วน video คือการโทรที่รองรับวิดีโอ

enum: voice, video

ทำความเข้าใจผลลัพธ์

201 พร้อม state=preparing หมายถึงเตรียมการโทรแล้ว ยังไม่ได้โทรออก บันทึก call_id เปิด join_url ที่เก็บเป็นความลับและกด Start call ก่อน expires_at ที่ส่งกลับ ยืนยันการเชื่อมต่อจากสถานะการโทรหรือ call.answered

หมายเหตุ

เตรียมการโทรเสียงหรือวิดีโอ WhatsApp แบบตัวต่อตัว (media_type: voice/video) โดย to.id คือ conversation_id และ to.type คือ user ไม่รองรับสตริงเบอร์โทรหรือการโทรกลุ่ม ระยะเวลาเตรียมเริ่มจากการสร้าง ค่าเริ่มต้น 2 นาที โดยยึด expires_at ที่ส่งกลับเป็นเวลาหมดอายุจริง เปิด join_url และกด Start call ก่อนหมดอายุ ไม่จำกัดระยะเวลาสายที่เชื่อมต่อแล้ว ต้องอนุญาตไมโครโฟน ส่วนกล้องเป็นตัวเลือก ห้ามเผยแพร่ลิงก์ใช้ครั้งเดียว

การตอบกลับ 201 · 201

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "direction": "outbound",
    "media_type": "video",
    "state": "preparing",
    "join_url": "https://calls.example.com/call/call_example#ticket=example-only",
    "expires_at": "2026-09-07T12:02:00Z"
  }
}

เนื้อหาการตอบกลับ

call_id

string

รหัสการโทร ใช้สำหรับวางสายด้วย

direction

string

ทิศทางการโทร

enum: outbound

media_type

string

voice คือเสียง ส่วน video คือการโทรที่รองรับวิดีโอ

enum: voice, video

state

string

สถานะการโทรปัจจุบัน

enum: preparing

join_url

string

ลิงก์ HTTPS อายุสั้นที่ใช้ได้ครั้งเดียว ห้ามบันทึกหรือเผยแพร่

format: uri

expires_at

string

เวลาหมดอายุการเตรียมในรูปแบบ RFC3339

format: date-time

การตอบกลับ

201

201 · 201

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

403

Forbidden

ระบบระบุคำขอได้ แต่ไม่อนุญาตให้ดำเนินการนี้

404

Not Found

ไม่พบทรัพยากรที่ร้องขอ โปรดตรวจสอบ error.code ร่วมกับการดำเนินการปัจจุบัน

409

Conflict

การดำเนินการขัดแย้งกับบัญชีของผู้ให้บริการหรือทรัพยากรที่มีอยู่

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

501

Not Implemented

provider ที่เลือกยังไม่รองรับการดำเนินการนี้

502

Bad Gateway

อะแดปเตอร์หรือ upstream provider ไม่สามารถทำรายการให้เสร็จได้

503

Service Unavailable

บริการ backend ที่จำเป็นไม่พร้อมใช้งานชั่วคราว

เมื่อคำขอล้มเหลว

ตรวจ HTTP และ error.code/numeric_code เก็บ request_id ตรวจสิทธิ์ทดสอบ บัญชี และ call_id หากสร้างแล้วขัดแย้ง ให้เรียกดูการโทรปัจจุบันก่อน ตรวจสถานะก่อนลองสร้างหรือวางสายซ้ำ อ้างอิงรหัสข้อผิดพลาด

invalid_request · 10000 · 400: ตรวจฟิลด์บังคับ รูปแบบ และเงื่อนไขช่องทาง แล้วแก้คำขอ
missing_api_key · 11000 · 401: ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่
invalid_api_key · 11001 · 401: ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่
account_not_found · 20020 · 404: ตรวจ account_id และใช้ X-Api-Key ของเวิร์กสเปซเจ้าของบัญชี คีย์ปัจจุบันไม่สามารถเข้าถึงบัญชีที่ไม่พบในเวิร์กสเปซนี้
unsupported_by_provider · 30003 · 501: ดูคู่มือความสามารถช่องทาง แล้วเลือกช่องทางหรือคำสั่งที่รองรับ การส่งซ้ำไม่เพิ่มการรองรับ
beta_feature_not_enabled · 41002 · 403: ติดต่อฝ่ายสนับสนุนทางเทคนิคเพื่อขอสิทธิ์ทดสอบแบบปิดให้เวิร์กสเปซ การส่งซ้ำหรือเปลี่ยน is_beta ในคำขอไม่ทำให้ได้สิทธิ์
call_already_active · 38000 · 409: เรียกดูการโทรปัจจุบันเพื่อรับ call_id รอให้จบหรือวางสายก่อนสร้างการโทรใหม่