從 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 或私人通話連結。

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