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

面向 Facebook 粉丝专页的 Messenger Webhook:消息与提及事件

Facebook 粉丝专页 Webhook 的 messages 字段,会在用户向粉丝专页发送 Messenger 消息时触发,推送一个 messaging 数组,其中包含发送者的粉丝专页范围 ID、粉丝专页的 ID、时间戳,以及消息的 mid 及其文本或附件。mention 字段会报告帖子和评论中新出现的粉丝专页提及。Meta 会对两者都使用 X-Hub-Signature-256 进行签名。

easyCoexistence 会将每个已连接粉丝专页的 Messenger 消息与提及,一到达即转发到您的 HTTPS 端点,使用该粉丝专页专属的密钥签名,且不保留副本;send_social_dm 可在 24 小时窗口内回复。

5 seconds

Meta 要求 Messenger Webhook 端点多快以 200 OK 响应每条通知。

1 hour

若投递失败持续这么久,Meta 会取消应用对该粉丝专页 Webhook 的订阅,直到重新订阅为止。

PSID

messages 事件中的发送者粉丝专页范围 ID,对每个用户与粉丝专页的组合都是唯一的。

Workplace only

Meta 参考文档如何标注 mention 事件的 sender 字段。

No history

过去的 Webhook 通知之后无法再查询,因此接收方必须自行存储所需内容。

messages 字段会发送什么?

当用户向粉丝专页发送 Messenger 消息时,系统会发出通知。Meta 会发送文本消息,或带附件的消息,附件类型包括图片、音频、视频、文件和贴纸等,分享的链接也可能以后备附件的形式到达。回复较早消息的消息会携带 reply_to,其值为该消息的 mid;快速回复则会携带其负载。

messages 事件是什么样的?

与动态变更不同,消息会放在粉丝专页 entry 内的 messaging 数组中到达。每个事件包含:sender,即用户的粉丝专页范围 ID;recipient,即粉丝专页;时间戳;以及 message,其中包含 mid 和 text,或包含 type 与负载 URL 的 attachments:

A messages event, as Meta sends it
{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1458692752478,
      "messaging": [
        {
          "sender": { "id": "<PSID>" },
          "recipient": { "id": "<PAGE_ID>" },
          "timestamp": 1458692752478,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "hello, world!"
          }
        }
      ]
    }
  ]
}

mention 字段会发送什么?

当粉丝专页在帖子或评论中被提及时,会发出 field 为 mention 的 change,其中携带 post_id 或 comment_id、消息内容、任何链接、图片或视频,以及 item 和 verb。Meta 提醒,部分帖子与评论 ID 因权限不足或隐私原因无法查询;其参考文档还标注 sender 字段仅适用于 Workplace,因此提及事件到达时可能不附带作者信息。

哪些 Messenger 字段不会被转发?

easyCoexistence 只为粉丝专页订阅 messages,不订阅 message_echoes、messaging_postbacks、message_reads 或 message_deliveries,因此粉丝专页发出的消息、按钮点击,以及已读和送达回执都不会被转发。使用 send_social_dm 发送的回复,会返回它自己的消息 ID。

事件如何到达您的端点?

Meta 会把粉丝专页的 Webhook 投递到粉丝专页所安装的应用,整个应用共用一个回调 URL。easyCoexistence 会检查每次投递的 X-Hub-Signature-256 签名,立即回应 Meta,并将每个已连接粉丝专页的 entry 转发到您为其设置的 HTTPS 端点,使用该粉丝专页自己的密钥签名。可通过 Claude 或 ChatGPT 中的 set_social_webhook_destination 设置,或通过 Partner API 的 PUT /channels/:id/webhook 设置;密钥只显示一次,再次设置会生成新密钥,URL 为 null 时则关闭转发。

转发的事件是什么样的?

一个 POST 请求,包含 platform 字段、account_id(即 list_social_accounts 返回的该粉丝专页连接的 ID)、粉丝专页的 ID 作为 external_id,以及 entry,即 Meta 为该粉丝专页提供的 entry,保持不变。sender.id 即为 send_social_dm 在 24 小时窗口内回复时所需的 recipient_id:

A forwarded messages event
{
  "platform": "facebook",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<PAGE_ID>",
  "entry": {
    "id": "<PAGE_ID>",
    "time": 1793318400000,
    "messaging": [
      {
        "sender": { "id": "<PSID>" },
        "recipient": { "id": "<PAGE_ID>" },
        "timestamp": 1793318399000,
        "message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
      }
    ]
  }
}

如何验证转发的事件?

每个转发的 POST 都带有 X-EC-Signature 请求头,格式为 t=<unix>,v1=<hex>,其中 v1 是时间戳、一个点(.)和原始请求正文的 HMAC-SHA256,并以该粉丝专页的签名密钥作为密钥。请按接收时的原样对正文计算签名,以恒定时间进行比较,并拒绝超过 5 分钟的时间戳。

Node.js: verifying X-EC-Signature
import crypto from "node:crypto";

// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
  const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  if (!sig.t || !sig.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(sig.t + "." + rawBody)
    .digest("hex");
  return expected.length === sig.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

投递会被重试吗?

easyCoexistence 不会重试。每个条目只转发一次,仅存于内存中,没有副本可用于重试;转发会等待 8 秒钟的响应,不跟随重定向,且只发送到解析为公网 IP 的 HTTPS 地址。Meta 指出,过去的通知之后无法再查询,因此请在消息到达时存储所需内容。在上游,Meta 在投递失败后会连续重试几次,因此同一条消息偶尔可能被您收到两次:请以其 mid 进行去重。

常见错误

  • 在回应之前就执行处理工作。转发不会重试,因此请立即返回 2xx,之后再处理事件。
  • 对解析后的 JSON 验证签名。请对原样到达的原始正文计算 HMAC。
  • 假设消息一定包含文本。贴纸、图片或分享的链接会以附件形式到达,且没有 text 字段。
  • 跳过去重。Meta 可能在失败后再次投递同一事件,因此在处理前请以 mid 作为键。
使用 EasyCoexistence 完成这些操作

使用 set_social_webhook_destination 或 Partner API 即可开启转发。每个连接每月 US$ 9 起,随连接数量增加降至 US$ 0.75,前 3 天免费。

常见问题

easyCoexistence 会为粉丝专页订阅哪些 Webhook 字段?

messages 对应 Messenger,mention 对应提及,此外还有 feed 对应粉丝专页的帖子与评论。

Messenger 贴纸或图片会附带文本吗?

不会。贴纸、图片或分享的链接会以附件形式到达,每个附件都有 type 和负载 URL,消息中不包含 text 字段。

Messenger Webhook 端点需要多快响应?

需在 5 秒内返回 200 OK。若投递失败持续 1 小时,Meta 会取消应用对该粉丝专页 Webhook 的订阅。

如何回复转发的消息?

在用户发送消息后的 24 小时内,调用 send_social_dm,并将事件中的 sender.id 作为 recipient_id。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间