WhatsApp 語音通話未響鈴？從 preparing 到接通的排查指南

建立 WhatsApp 語音通話傳回 201，但對方手機冇響鈴，應先搵出最後一個可以確認嘅階段。回應中嘅 state: preparing 只代表瀏覽器通話連結已準備好，唔代表已經撥號。不斷建立新通話，反而可能令最初嘅請求更難追查。

本文適用於 UnifyPort 透過非官方介面提供嘅內測版、由人手發起嘅單對單語音外撥，唔係 Meta WhatsApp Business Calling API 指南。首次接入同完整請求範例請睇語音通話接入教學。呢篇集中講點樣用應用程式現有嘅證據定位問題。

1. 先分清手上嘅證據可以確認啲乜

證據	可以確認	未能確認
建立傳回 201 同 preparing	通話連結已準備好	已撥號、已響鈴或已接通
目前通話查詢傳回 active	目前有已接通嘅系統管理通話	對應回調已送到應用程式
收到 call.answered	對應通話已接通	客服工單已更新
收到 call.ended	對應通話已結束	零秒就代表未接通
目前通話查詢傳回 data: {}	查唔到目前由 UnifyPort 管理嘅通話	之前通話嘅結果或手機端是否得閒

整合資料之前，先核對工作區、account_id 同通話識別碼。API 回應用 call_id，通話事件用 data.call.id。同一個訊息帳戶亦可能有另一位操作員發起其他通話。

2. 建立成功，但對方冇響鈴

按以下次序對照建立通話契約檢查：

1. 確認應用程式揀咗預期而且已授權嘅 WhatsApp 訊息帳戶，runtime_status 係 running。
2. 核對已儲存嘅請求：to.id 必須係該帳戶傳回嘅 conversation_id，to.type 係 user，media_type 係 voice，唔可以用電話號碼字串代替。
3. 比較目前時間同回應嘅 expires_at。準備期由建立起預設兩分鐘，但伺服器可以調整，所以要以傳回時間為準；呢個期限唔會限制已接通嘅通話時長。
4. 確認指定客服喺到期前開啟私密嘅一次性 join_url，並按 Start call。淨係開啟頁面唔會撥號。必須允許咪高峰，鏡頭則屬可選；已授予權限亦唔係接通證據。

連結過咗期就唔好重用。先查詢目前通話，再由操作員明確發起新嘅準備請求。如果以上檢查都通過，但仍然未能確認響鈴，應保留請求同瀏覽器證據；冇依據就唔好直接歸因於對方手機、瀏覽器或網絡故障。

3. 請求逾時或衝突，結果仍然唔清楚

建立請求逾時代表結果未知，唔代表一定冇建立成功。遇到衝突回應，要保留實際錯誤內容，唔好假設所有衝突都係同一原因。喺伺服器端執行唯讀嘅目前通話查詢：

curl 'https://api.unifyport.ai/v1/calls/active?account_id=acc_example' \
  -H 'X-Api-Key: <YOUR_API_KEY>'

已接通嘅語音外撥可能傳回：

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

冇目前系統管理通話時傳回：

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

查詢亦可能傳回 preparing、dialing、ringing 或 connecting，唔好假設每次通話都會經過所有狀態。佢唔會恢復遺失嘅通話連結，唔提供通話歷史，亦唔能夠判斷任何一方係咪正在 WhatsApp 手機端通話。查詢失敗唔可以當成成功傳回空結果。

將傳回嘅識別碼，同應用程式自己嘅通話及工單對應關係核對。唔好自動再建立一通，亦唔好為咗清空帳戶而掛斷歸屬不明嘅通話。結果仍然唔清楚，就先同操作員核對，再決定要唔要重試。確實需要掛斷時，回應中嘅 ended 同 failed 都係終態；唔可以單憑 failed 就不斷發送掛斷請求。

4. 已經接通，但冇收到回調

沿住資格、訂閱、投遞同應用程式儲存逐層檢查：

• 資格： is_beta 係由技術支援開通嘅唯讀工作區標記。通配訂閱唔會賦予內測資格；未有資格嘅工作區明確訂閱通話事件，會收到 403 beta_feature_not_enabled。
• 訂閱： 有資格嘅工作區，其 subscribed_events 應包含所需事件名稱，或者用 *、空列表或省略。明確列出事件時，只會匹配列出嘅事件。同時核對接通事件同結束事件。
• 投遞： 檢查設定嘅端點 URL、端點狀態、接收端存取日誌同 HTTP 回應。2xx 代表確認投遞，唔證明工單更新成功。
• 處理： 按投遞與驗簽指南檢查。設定 signing_secret 後，用 X-Device-Timestamp 同原始請求內容驗證 X-Device-Signature。分別檢查事件 id 去重、持久化，以及通話同工單嘅關聯。

投遞唔保證順序。接通事件遲過結束事件到達時，應補存接通證據，但唔好將終態通話重新顯示成進行中。淨係缺少回調，唔足以認定通話從未接通。

5. 零秒時長同空結果，要連同前後資料判斷

duration_seconds 統計接通時長並向下取整至秒，所以零秒唔能夠證明未接通。應同時儲存接通事件證據同結束原因。建立階段同步失敗可能冇結束事件，唔好令所有建立失敗都無限期等回調。

睇一個假設嘅排查例子：客服啟動已準備嘅通話，目前通話查詢顯示已接通，接收端亦已存低接通事件，但工單仍然顯示「等待中」。呢個時候應繼續檢查應用程式內嘅關聯同狀態更新，重撥唔會修復呢條記錄。之後查詢傳回空結果，亦唔能夠還原缺失嘅歷史，應使用已儲存嘅事件同請求。

6. 整理一份方便繼續定位嘅記錄

記錄工作區、訊息帳戶、對話同通話識別碼、request_id、UTC 時間、已遮蔽敏感資料嘅回應、客服嘅操作及權限狀態，以及現有接收端日誌。每項標明「已確認」或「未知」。截圖同共享日誌唔應包含 API key、簽署密鑰或完整嘅私密通話連結。

仍有解釋唔到嘅環節，可以將記錄交畀技術支援。本文唔代表支援來電、群組通話、錄音、轉寫、SIP/PBX 接入或 AI 自動外撥。