← 所有文章
指南

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 跑通傳送,再用標準事件把所有入站訊息接回業務系統。