登录开始免费试用
easyCoexistence 官方 API

通过 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 messages

只有对话中最近的 20 条消息会返回详情;更早的消息会返回错误,提示该消息已被删除。

2 per second

应用对每个 Facebook 主页可发起的 Conversations API 调用次数。

30 days

「请求」文件夹中超过此时长无活动的对话,不会出现在 API 结果中。

MESSAGING or MODERATE

读取对话时,令牌持有人必须能够执行的主页任务。

80006

Messenger API 调用对某个主页账户过于频繁时出现的错误;Meta 建议稍等片刻后重试。

如何列出主页的对话?

使用 GET /{page-id}/conversations,并将 platform 设为 messenger。结果包含一个 data 数组,其中是对话 ID,每个对话都带有 updated_time(即最后一条消息的添加时间),以及一个 paging 对象。Meta 的参考文档指出,此端点不支持基于时间的分页,因此请按 paging 对象翻页浏览列表。

Listing a Page's Messenger conversations
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 的形式到达)通向背后历史记录的最短路径:

One person's conversation
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 对象翻页。
使用 EasyCoexistence 完成这些操作

它没有用于 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 监控

验证时间