通話

查詢目前通話beta

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

目前只支援 WhatsApp 一對一語音和視像通話。傳回本系統管理嘅通話，沒有時 data 為 {}。不能判斷帳號或對方是否正在 WhatsApp 手機端通話。

GEThttps://api.unifyport.ai/v1/calls/active

支援渠道

呼叫前準備

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

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

參數從哪裡取得

account_id: 從建立或查詢帳號的回應取得 data.id。帳號屬於 X-Api-Key 對應的工作區。攞帳號

請求參數

請求標頭

X-Api-Key

string必填

工作區 API Key，工作區會由呢個標頭解析得出嚟。

查詢參數

account_id

string必填

目前工作區的帳戶 ID。

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

請求內容

呢個介面唔需要 JSON 請求內容。

如何理解結果

讀取 UnifyPort 目前管理的通話及 call_id/state。data={} 表示未找到此類通話，不代表雙方在 WhatsApp 手機端忙線或閒置。

回應 200 · active

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "state": "active",
    "direction": "inbound",
    "media_type": "voice"
  }
}

回應 200 · idle

{
  "request_id": "req_example",
  "data": {}
}

回應內容

call_id

string

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

maxLength: 128

state

string

目前通話狀態。

enum: preparing, dialing, ringing, connecting, active

direction

string

通話方向。

enum: inbound, outbound

media_type

string

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

enum: voice, video

回應

200

200 · active

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

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 都不會取得權限。