通話

建立通話beta

此功能現正內測，可聯絡技術支援申請開通工作區資格。

目前只支援 WhatsApp 一對一語音和視像通話。準備保密的一次性 join_url。開啟連結並按 Start call 後才向對方撥號。

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

支援渠道

呼叫前準備

在伺服器端使用資源所屬工作區的 X-Api-Key，執行範例前替換所有預留位置。

確認工作區已取得內測資格。建立通話前完成 WhatsApp 授權，並檢查 runtime_status=running。目標使用目前帳號下私人對話的 conversation_id。

在瀏覽器發起通話時須允許咪高峰，相機權限可選。

參數從哪裡取得

account_id: 從建立或查詢帳號的回應取得 data.id。帳號屬於 X-Api-Key 對應的工作區。攞帳號
to.id · to.type: 將 API 回傳的目前帳號下目標私人對話 conversation_id 原樣填入 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必填

發送 JSON 請求內容嘅時候請用 application/json。

請求內容

account_id

string必填

目前工作區的帳戶 ID。

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

to

object必填

一對一通話對象。

id

string必填

填入目前帳戶下目標對話的 conversation_id，使用介面傳回的原始值。

minLength: 1

type

string必填

目前只支援 user；group/channel 會傳回不支援錯誤。

enum: user, group, channel

media_type

string必填

voice 為語音，video 為支援視像的通話。

enum: voice, video

如何理解結果

201 且 state=preparing 表示通話已準備，尚未撥號。儲存 call_id，在回傳的 expires_at 前開啟保密的 join_url 並點擊 Start call；透過通話狀態或 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

請求錯誤

請求內容、路徑或者參數無效。

401

未授權

X-Api-Key 請求標頭缺少或者無效。

403

禁止存取

請求已識別，但唔允許執行呢個操作。

404

搵唔到資源

搵唔到請求嘅資源；請結合 error.code 同目前操作核對。

409

衝突

目前操作同現有嘅渠道帳號或者資源衝突。

500

伺服器錯誤

服務遇到咗未預期嘅錯誤。

501

渠道未實作

所選渠道未實作呢個操作。

502

上游閘道錯誤

渠道轉接器或者上游渠道未能完成呢個操作。

503

服務不可用

所需嘅後端服務暫時不可用。

失敗後如何處理

檢查 HTTP 狀態和 error.code/numeric_code，保留 request_id。核對內測資格、帳號與 call_id；建立衝突時先查詢目前通話。重試建立或掛斷前確認目前通話狀態。錯誤碼參考

invalid_request · 10000 · 400: 檢查必填欄位、格式與渠道條件，修正請求後再呼叫。
missing_api_key · 11000 · 401: 檢查 X-Api-Key 與工作區是否有效。
invalid_api_key · 11001 · 401: 檢查 X-Api-Key 與工作區是否有效。
account_not_found · 20020 · 404: 核對 account_id，並使用帳號所屬工作區的 X-Api-Key。此工作區下未找到的帳號無法使用目前 Key 存取。
unsupported_by_provider · 30003 · 501: 查看管道能力指南，選擇支援該動作的管道或操作；重複請求不會增加支援範圍。
beta_feature_not_enabled · 41002 · 403: 聯絡技術支援申請工作區內測資格。重複請求或在請求中修改 is_beta 都不會取得權限。
call_already_active · 38000 · 409: 先查詢目前通話取得 call_id，等待結束或掛斷後再建立新通話。