通話

掛斷通話beta

目前功能處於內測階段，可聯絡技術支援申請開通工作區資格。

目前僅支援 WhatsApp 一對一語音和視訊通話。使用 account_id 和 call_id 結束通話；忘記 call_id 時可先查詢目前通話。

POSThttps://api.unifyport.ai/v1/calls/{call_id}/hangup

支援渠道

呼叫前準備

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

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

參數從哪裡取得

account_id: 從建立或查詢帳號的回應取得 data.id。帳號屬於 X-Api-Key 對應的工作區。取得帳號
call_id: 使用目前帳號建立通話或查詢目前通話回傳的 call_id。遺失時，先查詢目前通話再掛斷。查詢目前通話

請求

curl -X POST 'https://api.unifyport.ai/v1/calls/call_example/hangup' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example"
}'

請求參數

請求標頭

X-Api-Key

string必填

工作區 API Key，工作區會由此標頭解析得到。

Content-Type

string必填

傳送 JSON 請求內容時請使用 application/json。

路徑參數

call_id

string必填

用於該 calls 路由的識別字。

maxLength: 128 · pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$

請求內容

account_id

string必填

目前工作區的帳號 ID。

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

如何理解結果

讀取回傳的 call_id 和 state。ended 和 failed 都是通話終態，重複掛斷可能回傳既有終態；不能將 HTTP 200 固定理解為 state=ended，也不要因 state=failed 自動重試。

回應 200 · 200

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "state": "ended",
    "direction": "outbound",
    "media_type": "voice"
  }
}

回應內容

call_id

string

通話識別碼，掛斷時使用。

maxLength: 128

state

string

目前通話狀態。

enum: ended, failed

direction

string

通話方向。

enum: inbound, outbound

media_type

string

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

enum: voice, video

回應

200

200 · 200

請求成功，回應內容範例如上。

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_not_found · 38003 · 404: 檢查 HTTP 狀態和 error.code/numeric_code，保留 request_id。核對內測資格、帳號與 call_id；建立衝突時先查詢目前通話。重試建立或掛斷前確認目前通話狀態。