如何通过 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 应用号码。
history Webhook 能回溯的时长,从企业接入 Cloud API 时开始计算。
企业的联系人和消息历史必须完成同步的接入后时限。
企业在 WhatsApp Business 应用中关闭历史记录分享时,history Webhook 返回的错误代码。
每次同步的运行频率;要重复同步,客户需断开接入并重新完成 Embedded Signup。
标志历史同步已完成的 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 及原因。
联系人 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。不包含群聊。
{
"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 的内容会被丢弃。
设置方法
- 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 小时内设置,否则该号码的历史记录永远不会被导入。
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 监控
验证时间