登入開始免費試用
easyCoexistence 官方 API

如何透過 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 要求其聯絡人及聊天紀錄,因此紀錄會直接送達您的端點,途中不作儲存,並全天候監察每個號碼。

180 days

history webhook 所涵蓋的時間範圍,由商戶接入 Cloud API 當日起計。

24 hours

商戶的聯絡人及訊息紀錄必須完成同步的接入後時限。

2593109

商戶在 WhatsApp Business 應用程式關閉紀錄分享時,history webhook 所回傳的錯誤代碼。

Once

每次同步可執行的頻率;如需重複,客戶須取消接入並重新完成 Embedded Signup。

100

標示 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 記錄原因。

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

聯絡人 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。群組聊天不包括在內。

A history webhook, as Meta sends it
{
  "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 的內容會被捨棄。

設定方法

  1. 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.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. 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 小時內設定,否則該號碼的聊天紀錄永遠不會被匯入。
使用 EasyCoexistence 完成這項設定

每個連接每月由 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 監察

驗證日期