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. 用一次新外撥驗證投遞
- 喺同一個已授權嘅 WhatsApp 訊息帳戶揀測試對話。用
POST /v1/calls準備通話,將傳回嘅call_id同應用程式任務關聯儲存。 201回應入面嘅state: preparing代表連結已準備好。操作員喺expires_at前開啟私密嘅join_url並按 Start call。- 測試通話接通並結束之後,查找接通事件同結束事件。將事件嘅
account_id、data.call.id同儲存嘅記錄核對。 - 用原有流程發送一條測試訊息,確認預期嘅訊息事件仍然到達接收端。
已啟用簽署嘅端點按投遞與驗簽指南驗證原始請求內容。按事件 id 去重,同時處理亂序。遲到嘅接通事件可以補充接通證據,通話記錄維持已結束。message.* 入面嘅通話記錄有獨立用途。
5. 排查回調缺失,保留還原設定
收唔到回調時,先核對精確嘅事件名稱、端點作用範圍同啟用狀態,再檢查接收端日誌、HTTP 回應同應用程式儲存。2xx 代表確認投遞,要另外驗證持久化同任務關聯。投遞、重試同死信重播都用當時嘅資格同訂閱設定。
保留原本嘅端點設定同簽署密鑰引用。需要還原時,提交原有完整設定,再驗證訊息投遞。需要協助時,可以將端點 ID、帳戶 ID、通話 ID、UTC 時間同已遮蔽敏感資料嘅接收結果交畀技術支援。API key、簽署密鑰同完整通話連結應保持私密。
令訊息接入變成一條穩定嘅產品管線。
先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。