WhatsApp 通話 Webhook:Calling API 事件,以及 Coexistence 號碼的通話
WhatsApp Business Calling API 的 calls Webhook 欄位回報以下事件:附 SDP answer 或 offer 的接通事件;通話狀態 RINGING、ACCEPTED 與 REJECTED;附 COMPLETED 或 FAILED 及通話時長的結束事件;以及 call_recording_available 或 call_transcription_available。Meta 的 Coexistence 指南列明,語音及視像通話在 WhatsApp Business 應用程式中維持不變,Cloud API 不支援,因此這些通話仍留在手機上。
easyCoexistence 透過 Coexistence 將您的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,讓您的 AI 與自動化功能回覆訊息及發送範本,而通話則繼續在您手機的應用程式中響鈴。
Cloud API 上的語音及視像通話,適用於透過 WhatsApp Business 應用程式接入的號碼;在應用程式中則維持不變。
號碼使用 Calling API 前所需的每日最低訊息上限(以不重複收件人計算)。
通話錄音及逐字稿在其 webhook 送達後仍可下載的時限。
通話 ID 的前綴,即把同一通話的接通、狀態及結束 webhook 串連起來的值。
應用程式接收通話 webhook 所需的權限,與接收訊息的權限相同。
通話 webhook 欄位回報什麼?
透過 Calling API 撥打或接聽的通話所發生的一切事件,以單一欄位呈現,每個階段一個事件。由商家發起的通話會產生一個接通事件、多個狀態更新及一個結束事件。透過 SIP 處理的通話則回報 call_created,而非 connect 事件,且不含 SDP 會話。另有一個相關事件位於其他欄位:客戶回覆通話權限請求時,回覆會以 messages 欄位送達,類型為 interactive 的訊息 call_permission_reply。
通話 webhook 看起來是怎樣的?
與所有 WhatsApp webhook 相同的封套,在 value 下有一個 calls 陣列,field 設為 calls。direction 為 BUSINESS_INITIATED 或 USER_INITIATED;from 與 to 載有電話號碼,to_user_id 為客戶的 BSUID。客戶若使用用戶名稱,任一號碼都可能缺失。metadata.phone_number_id 標識您的號碼,與其他任何欄位相同。以下是 Meta 的 Call Connect 範例,佔位符與 Meta 所列相同:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315553601",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<CALLEE_NAME>",
"username": "<USERNAME>"
},
"wa_id": "16315553602",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
],
"calls": [
{
"id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"to": "16315553601",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "16315553602",
"event": "connect",
"timestamp": "1671644824",
"direction": "BUSINESS_INITIATED",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
]
},
"field": "calls"
}
]
}
]
}terminate 事件還會添加哪些欄位?
terminate 是大多數系統會儲存的事件,因為它會結束通話。根據 Meta 的參考文件,其欄位如下:
- status:通話在沒有預期外錯誤的情況下結束時為 COMPLETED,包括未接來電;未能接通或中斷時為 FAILED。
start_time、end_time及以秒計的 duration:只在對方接聽時出現。- errors:在 FAILED 通話中包含 code、message、href 及
error_data.details。 biz_opaque_callback_data:您自行設定的追蹤字串,當您在發起或接聽通話時傳入時才會出現。
通話 webhook 可以在 Coexistence 號碼上使用嗎?
Meta 的 Coexistence 指南在其功能比較表中回答了此問題:對於以此方式接入的號碼,語音及視像通話在 WhatsApp Business 應用程式中沒有任何變化,且 Cloud API 不支援。Calling API 自身的先決條件從另一方面印證了這點:商家號碼必須以 Cloud API 使用,而非透過 WhatsApp Business 應用程式。因此在 Coexistence 號碼上,客戶照舊撥打電話,來電會在手機的應用程式中響鈴,而 calls 欄位沒有任何可回報的內容。需要在軟件中處理通話的商家,應單獨使用 Cloud API 上的號碼。
同一通話的各事件如何銜接?
透過通話 ID,即以 wacid 開頭、並在該通話的每個事件中重複出現的值。由商家發起的通話會回報附 SDP answer 的接通事件、RINGING,隨後是 ACCEPTED 或 REJECTED 狀態,最後是 terminate。由用戶發起的通話會回報附 SDP offer 的接通事件,供您的系統應答,然後是 terminate。錄音及逐字稿事件(如已啟用)會在 terminate 之後出現。請以 id 加 event 作為已儲存事件的鍵,因為重試會重複送達,且不保證到達順序。Calling API 先決條件的完整清單,載於有關 Coexistence 號碼通話的頁面。
您的 AI 能如何處理 Coexistence 號碼上的通話?
在對話中運作,而通話仍由手機另一端的人處理。easyCoexistence 不訂閱 calls 欄位,也沒有通話工具;其連接器與自動化功能只涵蓋訊息及範本。實際上,AI 回覆可以告知客戶何時有人可以通話、應撥打哪個號碼;關鍵字自動化可以用該資訊回覆「call」或「phone」;而擁有人則照常在 WhatsApp Business 應用程式中接聽來電。
常見錯誤
- 為 Coexistence 號碼訂閱通話並等待事件。Meta 列明這些號碼在 Cloud API 上不支援通話。
- 期望每個 terminate 都有 start_time 及 duration。這些欄位只在通話獲接聽時出現;未接來電仍會以 COMPLETED 結束。
- 在 calls 欄位中尋找權限回覆。它們會以 interactive call_permission_reply 的形式出現在 messages 中。
- 把錄音及逐字稿留在 Meta 處。兩者均可於其 webhook 送達後 7 天內下載,之後便不再存在。
每個號碼均受 24/7 監察,包括 14 天規則,即應用程式 14 天未被開啟,號碼便會斷開連接。每個已連接號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,首 3 天免費。
常見問題
當號碼透過 Coexistence 接入 API 時,客戶會失去通話按鈕嗎?
Meta 的 Coexistence 指南列明,語音及視像通話在 WhatsApp Business 應用程式中維持不變。客戶撥打同一號碼,擁有人則在手機上的應用程式中接聽。
Calling API 的收費與訊息相同嗎?
不同。Meta 的定價頁面指出,Calling API 有不同的收費,並指向另一份獨立的通話定價文件,因此通話費用不會出現在訊息狀態的 pricing 物件中。
Calling API 的通話可以錄音或轉錄嗎?
可以,但須已啟用錄音或轉錄。通話結束後,Meta 會發送 call_recording_available(附音頻 media id)或 call_transcription_available(附 JSON 文件 id),通常在一分鐘內送達。
通話 webhook 可以送往與應用程式不同的端點嗎?
可以。calls 是 Meta 允許 WhatsApp Business 帳戶或電話號碼路由至其他回調 URL 的欄位之一,與 messages 及 Coexistence 欄位並列。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期