從 WhatsApp 聊天到人工通話：UnifyPort 語音與視訊通話內測

客戶已經在 WhatsApp 說明問題，但再多打一段文字，也未必能說得更清楚。客服可能需要直接確認配送細節，或透過鏡頭看見實際狀況。UnifyPort 通話內測新增了通話流程：你的業務系統先準備 WhatsApp 一對一語音或視訊通話，再由客服在瀏覽器中發起，後端則接收通話狀態事件。

目前範圍是由人工操作的 WhatsApp 撥出通話。每個工作區都需要透過技術支援開通資格。僅建立 API key 並不會啟用通話功能，這次內測也尚未開放來電接聽。

這次通話內測新增了什麼

通話 API 參考文件現在說明了三項操作：

• POST /v1/calls 準備語音或視訊通話，並傳回短期有效、僅供一次使用的 join_url。
• GET /v1/calls/active 取得指定帳號目前由 UnifyPort 管理的通話。
• POST /v1/calls/{call_id}/hangup 結束指定通話。

另有兩個 webhook 事件，協助應用程式追蹤通話進度：call.answered 通知通話已接通，call.ended 通知通話結束，並附上結束原因及接通時長。開發者可以用這些介面，在既有客服流程中加入人工通話步驟。

API 請求的作用是準備通話。客服必須開啟傳回的連結，再點擊 Start call 才會撥號。 請在操作介面中清楚呈現這個步驟，讓客服在撥出前確認選中的客戶。

何時適合從文字聊天轉為通話

以下是假設的客服情境：

• 訂單確認： 配送安排用短訊息難以說清楚，客服與客戶可以直接通話確認。
• 問題排查： 客服以語音引導客戶依序完成檢查。
• 視覺協助： 透過視訊，讓客戶展示商品或安裝現場的問題。

這些都是可設計的應用流程，並非已驗證的客戶成果。團隊仍需自行決定何時通話，並在自己的客服系統記錄後續處理事項。

收件匣可以在選中的 WhatsApp 聊天旁提供通話操作。通話目標必須使用已連接訊息帳號中該聊天的 conversation_id；通話 API 不接受任意電話號碼字串。客服指派與問題結案仍由你的應用程式管理，相關設計可參考 WhatsApp 共用收件匣指南。

先準備通話，再由客服發起

首先，為工作區申請內測資格，並連接已完成授權的 WhatsApp 訊息帳號。如果你仍在設定帳號存取權限，可以參考 QR 與 Passkey 驗證指南；帳號授權是另一個需要完成的接入步驟。

從後端使用工作區的 X-Api-Key 傳送建立請求。以下 JSON 展示文件定義的 request body；送至 POST /v1/calls 前，請將 acc_example 與 <conversation_id> 替換為選中的帳號及其實際會話識別碼：

{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}

語音通話使用 voice，支援視訊的通話使用 video。API key 應保留在伺服器端，再將傳回的 join_url 私下提供給預定操作的客服。

建立成功時會傳回 201 Created，包含 call_id、state: preparing、join_url 及 expires_at。這個回應不代表已向客戶撥號，也不代表客戶已接聽。

準備期預設為從建立起算兩分鐘。伺服器可能調整期限，因此請以傳回的 expires_at 為實際截止時間。客服必須在期限前開啟連結並點擊 Start call。這個準備期限不限制已接通通話的時長。

瀏覽器必須取得麥克風使用權限，攝影機權限則為選用。請將連結視為僅供一次使用的私人連結，不要公開，也不要將完整 URL 寫入紀錄。

將通話狀態接回工作流程

在自己的系統中，將傳回的 call_id 關聯至選中的帳號、會話與客服任務。需要時可以透過查詢目前通話介面取得受管理的通話，遺失通話識別碼時也可以使用。如果目前沒有受管理的通話，回應會傳回 data: {}。這個介面無法判斷客服或客戶是否正在 WhatsApp 手機版中通話。

訂閱 call.answered 與 call.ended，即可更新應用程式中的通話紀錄。若使用指定的 subscribed_events 清單，必須列入這兩個事件名稱。具備內測資格的工作區若使用 *、空清單或省略清單，訂閱範圍也會包含允許的通話事件。一般工作區即使使用萬用字元訂閱，也不會收到通話事件。

結束事件包含 data.call.id、reason 及 duration_seconds。時長計算的是接通時間，秒數無條件捨去，因此僅憑 0 不能判定通話未接通；也應記錄接通事件。建立階段若同步失敗，可能沒有結束回呼，因此 HTTP 錯誤需要另外處理。

請依照 webhook 投遞參考文件實作簽章驗證與依事件 ID 去除重複。應用程式可以利用這些狀態安排後續處理；通話結束本身不代表客戶問題已解決。

目前內測的能力邊界

這次內測支援透過瀏覽器流程發起的 WhatsApp 一對一語音與視訊通話。群組通話、頻道通話、其他消息平台的通話及來電處理，均不在目前範圍內。文件中的 call.incoming 是預留契約；事件目錄中列有這個名稱，並不代表已開放接聽來電。

這次內測不提供錄音、轉寫、SIP/PBX 整合或 AI 語音客服能力。UnifyPort 提供的是非官方介面；本文說明 UnifyPort 自身的通話契約，不將它稱為 Meta 官方 WhatsApp Business Calling API。

工作區旗標 is_beta 是唯讀欄位，預設關閉，需要由技術支援開通資格。沒有資格的工作區呼叫通話 API 時，會收到 403 beta_feature_not_enabled，numeric code 為 41002。設定 metadata 或傳送工作區 PATCH 都不能自行啟用資格。

試用前常見問題

可以只提供電話號碼就發起通話嗎？

不可以。請使用所選 WhatsApp 訊息帳號底下的實際 conversation_id，並設定 to.type: user。

呼叫 API 後會立即撥號嗎？

不會。API 只準備通話連結，需要由人工開啟連結，並在 expires_at 前點擊 Start call 才會撥號。

每通通話只能持續兩分鐘嗎？

不是。兩分鐘是從建立起算的預設準備期，不是已接通通話的時長上限。

取得內測資格後，團隊就能接聽來電嗎？

不行。目前內測尚未開放來電接聽，is_beta: true 的工作區也一樣。

為團隊申請資格

聯絡技術支援，申請通話內測資格，為你的工作區開通存取權限。為了協助團隊了解用途，可以提供工作區 ID、WhatsApp 客服情境，以及需要語音或視訊通話。這些資訊有助於說明申請內容，並非自動加入內測的程序；請勿在申請中提供 API key 或私人通話連結。

資格開通後，依照建立通話參考文件，選擇一個明確的測試會話，接入客服的瀏覽器通話流程。先從你希望改善的工作流程開始，再透過測試評估人工通話如何融入客服應用程式。