← 所有文章
指南

WhatsApp 開放外撥後,一般工作區點樣接收通話回調?

UnifyPort 一般工作區已經可以準備 WhatsApp 單對單外撥。如果 Webhook 端點只訂閱 ["*"],訊息仍然可以正常到達,但可能收唔到外撥回調。要收到接通同結束事件,要分別明確訂閱 call.answered 同 call.ended。

建立通話文件適用於透過 UnifyPort 非官方介面由人手發起嘅語音同視像外撥。call.incoming 仍然係為將來嘅來電功能預留。

1. 核對工作區嘅訂閱規則

工作區訂閱方式外撥事件
一般["*"]、[] 或者省略列表只匹配一般事件
一般喺 subscribed_events 明確列出事件名稱接收列出嘅外撥事件
內測明確列表、通配、空列表或者省略接收匹配嘅外撥事件

端點符合條件時,明確嘅事件名稱會匹配對應回調。一般工作區可以同時填寫 * 同兩個外撥事件名稱,保留一般事件嘅通配範圍。一般工作區明確訂閱預留嘅 call.incoming 會收到 403 beta_feature_not_enabled(41002)。

2. 更新之前先讀取端點設定

透過查詢 Webhook 端點確認目標 URL、狀態、目前訂閱同重試策略。核對端點屬於工作區,定係某個訊息帳戶。更新會保留現有嘅帳戶綁定。

更新 Webhook 端點會取代設定。提交之前準備完整嘅目標設定,保留目前 URL、狀態同重試策略。已經啟用簽署時,喺自己嘅安全設定攞返現有密鑰。查詢回應提供 signing_enabled,密鑰由應用程式端保管。省略 signing_secret 或者傳空值會關閉簽署。省略重試策略會恢復做首次投遞後預設重試三次。

3. 加入外撥事件,同時保留訊息訂閱

如果端點目前用通配訂閱,將以下請求內容提交到 PATCH /v1/webhook-endpoints/{endpoint_id}。範例假設端點已啟用、已啟用簽署,而且原本設定為重試三次。用實際嘅 URL、狀態、密鑰同重試設定取代範例值。API key 同簽署密鑰應保存在伺服器端。

{
  "url": "https://support.example.com/webhook",
  "status": "active",
  "subscribed_events": ["*", "call.answered", "call.ended"],
  "signing_secret": "<EXISTING_WEBHOOK_SIGNING_SECRET>",
  "retry_policy": { "max_attempts": 3 }
}

如果端點用明確列表,複製現有事件名稱,再加入兩個外撥事件。例如原列表只包含 message.received 同 message.read,合併後嘅陣列如下。將呢個陣列用作完整更新請求嘅 subscribed_events 欄位值。

["message.received", "message.read", "call.answered", "call.ended"]

更新後再查一次端點,核對 URL、狀態、訂閱、簽署狀態同重試設定。確認接收端可以處理兩種通話事件同原有訊息事件。

4. 用一次新外撥驗證投遞

  1. 喺同一個已授權嘅 WhatsApp 訊息帳戶揀測試對話。用 POST /v1/calls 準備通話,將傳回嘅 call_id 同應用程式任務關聯儲存。
  2. 201 回應入面嘅 state: preparing 代表連結已準備好。操作員喺 expires_at 前開啟私密嘅 join_url 並按 Start call。
  3. 測試通話接通並結束之後,查找接通事件同結束事件。將事件嘅 account_id、data.call.id 同儲存嘅記錄核對。
  4. 用原有流程發送一條測試訊息,確認預期嘅訊息事件仍然到達接收端。

已啟用簽署嘅端點按投遞與驗簽指南驗證原始請求內容。按事件 id 去重,同時處理亂序。遲到嘅接通事件可以補充接通證據,通話記錄維持已結束。message.* 入面嘅通話記錄有獨立用途。

5. 排查回調缺失,保留還原設定

收唔到回調時,先核對精確嘅事件名稱、端點作用範圍同啟用狀態,再檢查接收端日誌、HTTP 回應同應用程式儲存。2xx 代表確認投遞,要另外驗證持久化同任務關聯。投遞、重試同死信重播都用當時嘅資格同訂閱設定。

保留原本嘅端點設定同簽署密鑰引用。需要還原時,提交原有完整設定,再驗證訊息投遞。需要協助時,可以將端點 ID、帳戶 ID、通話 ID、UTC 時間同已遮蔽敏感資料嘅接收結果交畀技術支援。API key、簽署密鑰同完整通話連結應保持私密。

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。