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 自動外撥。