登录开始免费试用
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 应用号码。

180 days

history Webhook 能回溯的时长,从企业接入 Cloud API 时开始计算。

24 hours

企业的联系人和消息历史必须完成同步的接入后时限。

2593109

企业在 WhatsApp Business 应用中关闭历史记录分享时,history Webhook 返回的错误代码。

Once

每次同步的运行频率;要重复同步,客户需断开接入并重新完成 Embedded Signup。

100

标志历史同步已完成的 progress 值。

导入如何开始?

首先要为号码设置 Webhook 目的地。若连接时会话中已设置 webhook_url,或在连接后 24 小时内通过 PUT /connections/{id}/webhook 设置,easyCoexistence 会向 Meta 请求一次数据:先按 Meta 记载的顺序,用 sync_type smb_app_state_sync 调用 POST /{phone_number_id}/smb_app_data 获取联系人,再用 history 获取聊天记录。号码的事件日志会记录 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,以及 metadata.timestamp。移除时不含姓名。企业在 WhatsApp Business 应用中新增、编辑或移除联系人时,Meta 在导入后仍会持续发送这些 Webhook,让您的通讯录与手机保持一致。

history 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 应用会询问企业是否分享聊天历史。若企业拒绝,会收到一个不含消息的 history Webhook,其 errors 数组中的代码为 2593109,标题为“History sync is turned off by the business from the WhatsApp Business App”。联系人仍会送达,号码连接后的实时消息也照常发送。

导入能否再次运行?

同一连接上不能。Meta 只允许每次接入后 24 小时内同步一次,且无法重放。要再次运行,客户需断开号码并重新连接,这会被视为一次新的接入:只要目的地仍已保存,easyCoexistence 就会再次请求导入,因此请按每条消息的 id 去重。号码在 14 天规则之后重新接入的情况也包括在内。

发送连接链接前需要准备什么?

端点须已上线并能正常响应。设置目的地时,Meta 会用 GET 握手检查网址,导入随即只请求一次。若握手失败,号码仍会连接,但没有目的地,会话的 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 完成这些操作

Webhook 就绪后,它会立即向 Meta 请求这些号码的联系人与聊天记录,历史数据直接发送到您的端点,途中不做任何存储,并全天候 24/7 监控每个号码。每个连接每月 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 监控

验证时间