如何透過 API 匯入 WhatsApp Business 應用程式的聊天紀錄及聯絡人
透過 Coexistence 連接的 WhatsApp Business 應用程式號碼,可於接入後 24 小時內,一次過將現有聯絡人及最多 180 天的一對一聊天紀錄傳送至 API。聯絡人以 smb_app_state_sync webhook 送達,聊天紀錄則以 history webhook 送達,並按 metadata.chunk_order 排序分段;metadata.progress 達 100 即表示匯入完成。商戶可在應用程式內選擇是否分享聊天紀錄。
easyCoexistence 透過 Coexistence 連接您客戶的 WhatsApp Business 應用程式號碼,並於您的 webhook 就緒時即時向 Meta 要求其聯絡人及聊天紀錄,因此紀錄會直接送達您的端點,途中不作儲存,並全天候監察每個號碼。
history webhook 所涵蓋的時間範圍,由商戶接入 Cloud API 當日起計。
商戶的聯絡人及訊息紀錄必須完成同步的接入後時限。
商戶在 WhatsApp Business 應用程式關閉紀錄分享時,history webhook 所回傳的錯誤代碼。
每次同步可執行的頻率;如需重複,客戶須取消接入並重新完成 Embedded Signup。
標示 history 同步已完成的 progress 值。
匯入如何開始?
首先須在號碼上設定 webhook 目的地。當號碼在連接工作階段中已設定 webhook_url 而完成連接,或在連接後 24 小時內以 PUT /connections/{id}/webhook 設定,easyCoexistence 會向 Meta 一次性要求提供數據:先以 sync_type smb_app_state_sync 呼叫 POST /{phone_number_id}/smb_app_data 取得聯絡人,再以 history 取得聊天紀錄,次序與 Meta 所述一致。號碼的事件日誌會以 history_sync_requested 記錄 Meta 的 request_id 值以供支援查閱;若失敗,則以 history_sync_failed 記錄原因。
聯絡人 webhook 包含哪些內容?
欄位為 smb_app_state_sync,其 value 內含 state_sync 陣列。每個項目的類型為 contact,包含一個具有 full_name、first_name 及 phone_number 的聯絡人物件、add 或 remove 的 action,以及 metadata.timestamp。移除時不會附上姓名。匯入完成後,每當商戶在 WhatsApp Business 應用程式中新增、編輯或移除聯絡人,Meta 仍會繼續傳送此 webhook,令您的通訊錄與手機保持一致。
聊天紀錄 webhook 包含哪些內容?
欄位為 history,其 value 內含 history 陣列。每個項目包含 metadata(內有 phase、chunk_order 及 progress)以及 threads,每位客戶一個。thread 的 id 為客戶的電話號碼,messages 列出該一對一對話的所有訊息,包括收到及發出的,並以 from 識別發送方。每則訊息包含 id、timestamp、type,內容置於該類型名稱之下,以及 history_context.status,例如 READ 或 DELIVERED。群組聊天不包括在內。
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WABA_ID>",
"changes": [
{
"field": "history",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
"history": [
{
"metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
"threads": [
{
"id": "<CUSTOMER_NUMBER>",
"messages": [
{
"from": "<CUSTOMER_NUMBER>",
"id": "wamid.<ID>",
"timestamp": "1790726400",
"type": "text",
"text": { "body": "<MESSAGE_TEXT>" },
"history_context": { "status": "READ" }
}
]
}
]
}
]
}
}
]
}
]
}媒體訊息如何匯入?
首先以佔位符形式匯入。媒體訊息會帶有 type media_placeholder,沒有 content,亦沒有媒體 ID。其後 Meta 會另行傳送載有媒體 ID 的 history webhook,但僅限於接入後 14 天內發送的媒體;請以客戶的存取權杖向 Meta 提取這些檔案。超過該期限的媒體會維持為佔位符,因此應顯示為無法使用的附件,而非在對話中留下空白。
分段的到達次序為何,匯入何時完成?
不一定按次序到達。Meta 會將聊天紀錄分為三個階段,由最新開始:階段 0 為接入前一天,階段 1 回溯至第 90 天,階段 2 則回溯至第 180 天。分段可能次序錯亂,因此請按 metadata.chunk_order 排序。metadata.progress 代表整個同步的百分比,100 即表示完成;單憑階段編號無法判斷某一階段是否已經完成。
如果商戶拒絕分享聊天紀錄會怎樣?
連接期間,WhatsApp Business 應用程式會詢問商戶是否分享其聊天紀錄。若商戶拒絕,會以不含 messages 的 history webhook 送達,並附有 errors 陣列,其代碼為 2593109,標題為 History sync is turned off by the business from the WhatsApp Business App。聯絡人仍會送達,而號碼連接後,即時訊息亦會照常傳送。
匯入可否重新執行?
在同一連接上不可以。Meta 只允許每次同步一次,且須於接入後 24 小時內完成,不可重播。如要重新執行,客戶須先取消號碼的接入,再重新連接;這會被視為一次新的接入。只要目的地仍設定於 easyCoexistence,系統便會再次要求匯入,因此請以每則訊息的 id 去除重複項目。號碼在 14 天規則之後重新連接,亦屬此情況。
發出連接連結前,應先準備好什麼?
您的端點須已正常運作並能作出回應。當目的地被套用時,Meta 會以 GET 握手驗證 URL,匯入會隨即要求一次。若握手失敗,號碼仍可連接,但不會設定目的地,工作階段的 last_error 會說明原因;除非您修正端點,並於 24 小時內以 PUT /connections/{id}/webhook 設定,否則不會匯入任何資料。未設定 webhook_url 的號碼完全不會匯入,因為傳送至 easyCoexistence 的內容會被捨棄。
設定方法
- Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
常見錯誤
- 拒絕大型聊天紀錄分段。Meta 的負載可達 3 MB,而 Express 預設只會解析最多 100 KB 的 JSON,因此請提高上限,否則分段會失敗,Meta 亦會不斷重試。
- 按抵達次序處理分段。分段可能次序錯亂,因此請按 metadata.chunk_order 排序,並待 progress 達 100 後才將匯入視為完成。
- 未經去除重複便寫入紀錄。即時訊息可能與匯入內容重疊,而重新連接亦會再次執行匯入,因此請以每則訊息的 id 作為鍵值去除重複項目。
- 端點未能回應 Meta 的握手前便發出連接連結。目的地因而未被套用,除非您於 24 小時內設定,否則該號碼的聊天紀錄永遠不會被匯入。
每個連接每月由 US$ 9 降至 US$ 0.75,連接越多越便宜,首 3 天免費。
常見問題
WhatsApp 聊天紀錄的匯入可回溯多久?
最多回溯至號碼接入 Cloud API 之前 180 天,涵蓋雙向一對一聊天。
群組聊天會被匯入嗎?
不會。Meta 不包括屬於群組聊天的訊息。
客戶舊有的 WhatsApp 聊天會送達我的 webhook 嗎?
會。若商戶選擇在應用程式內分享,最多 180 天的一對一聊天將於接入後 24 小時內送達一次。
easyCoexistence 會保存已匯入聊天的副本嗎?
不會。Meta 會將聊天紀錄直接傳送至您的 webhook_url,與即時訊息相同,途中不作儲存。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期