通过 API 读取 Messenger 对话历史
使用 GET /{page-id}/conversations?platform=messenger 读取 Facebook 主页的 Messenger 历史记录,该请求会列出对话 ID 及其最后更新时间。随后,使用 GET /{conversation-id}?fields=messages 获取消息 ID,再用 GET /{message-id} 获取每条消息的发送者、接收者、文本和附件。Meta 只返回对话中最近 20 条消息的详情,且调用需要带有 pages_messaging 权限的主页访问令牌。
easyCoexistence 会在新的 Messenger 消息到达时将其转发至您的端点,而 send_social_dm 可在 24 小时窗口内回复,可通过 Claude、ChatGPT 或您自己的代码使用。
只有对话中最近的 20 条消息会返回详情;更早的消息会返回错误,提示该消息已被删除。
应用对每个 Facebook 主页可发起的 Conversations API 调用次数。
「请求」文件夹中超过此时长无活动的对话,不会出现在 API 结果中。
读取对话时,令牌持有人必须能够执行的主页任务。
Messenger API 调用对某个主页账户过于频繁时出现的错误;Meta 建议稍等片刻后重试。
如何列出主页的对话?
使用 GET /{page-id}/conversations,并将 platform 设为 messenger。结果包含一个 data 数组,其中是对话 ID,每个对话都带有 updated_time(即最后一条消息的添加时间),以及一个 paging 对象。Meta 的参考文档指出,此端点不支持基于时间的分页,因此请按 paging 对象翻页浏览列表。
GET /{page-id}/conversations?platform=messenger
{
"data": [
{ "id": "<CONVERSATION_ID>", "updated_time": "<TIME>" },
{ "id": "<CONVERSATION_ID>", "updated_time": "<TIME>" }
],
"paging": { ... }
}如何找到某个人的对话?
在同一请求中添加 user_id,值设为该用户的主页范围 ID。Meta 会返回该主页与此用户之间的对话 ID。这是从 messages Webhook(其中 PSID 以 sender.id 的形式到达)通向背后历史记录的最短路径:
GET /{page-id}/conversations?platform=messenger&user_id=<PSID>
{ "data": [ { "id": "<CONVERSATION_ID>" } ] }如何读取对话中的消息?
分两步进行。使用 GET /{conversation-id} 并设置 fields=messages,返回对话中的消息 ID,每个 ID 附带 created_time,最新的排在最前;然后使用 GET /{message-id},并指定所需字段(例如 id、created_time、from、to、message 和 reply_to),即可返回单条消息的内容。默认字段为 id 和 created_time,没有数据的字段会从响应中省略。
可以读取哪些字段?
对话与消息所暴露的字段不同。以下是 Meta 参考文档中列出的主页消息字段:
- 对话:id、
updated_time、participants(包含其 ID、name 和 email)、messages,以及开启 Conversation Routing 后的is_owner。 - 消息:id、
created_time、from 和 to(各自包含 ID、name 和 email),以及 message(文本内容,无文本时为空)。 - attachments:文件、图片和视频及其 CDN URL,以及
is_unsupported(仅当消息包含不受支持的内容时返回)。 - reactions、
reply_to(包含其所回复的 mid 与is_self_reply),以及分享的帖子和 Reels 的 shares。 - tags:消息所在的文件夹和来源,例如 inbox、read 或 source:chat。
能回溯读取多久以前的内容?
对于 ID,可以回溯到对话的起点,但对于内容则不然。Meta 指南称,对话端点会返回对话中的所有消息 ID,而详情仅返回最近 20 条消息;请求更早的消息会返回错误,提示该消息已被删除。「请求」文件夹中已有 30 天未活动的对话,完全不会返回。
需要哪些权限和任务?
需要由能够在该主页上执行 MESSAGING 或 MODERATE 任务的人员所获得的主页访问令牌,并具备 pages_manage_metadata、pages_read_engagement 和 pages_messaging 权限。若要读取与应用、主页或业务中没有任何角色的人员之间的对话,则需要 Advanced Access,须通过 App Review 获得。
调用有哪些限制?
Meta 的速率限制规定,Conversations API 每个主页每秒 2 次调用,超出限制的调用会返回 613 或 80006,并提示「There have been too many messenger api calls to this Page account」。达到 Meta 高流量上限(例如每秒发送超过 40 条消息)的主页,在流量下降之前无法列出对话,但仍可读取单个对话中的新消息。
何时应使用 API 而非 Webhook?
用于获取过去的消息。Webhook 实时推送新消息,而 Meta 指出过去的通知事后无法查询,因此 Conversations API 是集成用来读取其开始监听之前的内容,或在停机后补齐消息的途径。开启 Conversation Routing 后,is_owner 字段会将列表缩小到应用负责回复的对话,Meta 建议停机后借此恢复。
easyCoexistence 如何读取 Messenger 历史记录?
该功能不读取历史记录。主页连接时会授予 pages_messaging、pages_manage_metadata 和 pages_read_engagement 权限,但没有任何工具调用 Conversations API,也不会提供主页令牌。新消息到达时,会经由 set_social_webhook_destination 转发至您的端点,转发时不保留副本,因此您自己的系统可保留所需的历史记录。
常见错误
- 误以为列表调用会返回消息内容。对话端点只返回消息 ID,应从 /{message-id} 读取每条消息的字段。
- 指望获取完整历史。详情仅限最近 20 条消息,因此应在消息到达时,从 Webhook 中保存所需内容。
- 反复轮询新消息。每个主页每秒仅 2 次调用,轮询循环很快就会触及速率限制,而 messages Webhook 会在消息发生时即时推送。
- 用 since 和 until 按日期分页。对话端点不支持基于时间的分页,请改为按 paging 对象翻页。
它没有用于 Conversations API 的工具,因此更早的历史记录需在主页收件箱中查看。每个连接每月 US$ 9 至 US$ 0.75,连接越多越便宜,前 3 天免费试用。
常见问题
Conversations API 是否包含主页自己发出的消息?
包含。消息的 from 和 to 字段会标明用户或主页,因此对话中的消息包含双方。
无需 App Review 也能读取 Messenger 对话吗?
对于在应用或主页中拥有角色的人员,Standard Access 已足够。与其他任何人的对话则需要 Advanced Access,须通过 App Review 获得。
Conversations API 能发送回复吗?
不能。Meta 的对话参考文档指出,该 edge 不支持发布;回复需通过 /{page-id}/messages 上的 Send API 发送。
easyCoexistence 会存储我的 Messenger 对话吗?
默认不保留。转发的事件会继续传递,且不保留副本;开启自动化后,消息文本保留 7 天,自动化运行日志保留 30 天。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间