面向 Facebook 粉丝专页的 Messenger Webhook:消息与提及事件
Facebook 粉丝专页 Webhook 的 messages 字段,会在用户向粉丝专页发送 Messenger 消息时触发,推送一个 messaging 数组,其中包含发送者的粉丝专页范围 ID、粉丝专页的 ID、时间戳,以及消息的 mid 及其文本或附件。mention 字段会报告帖子和评论中新出现的粉丝专页提及。Meta 会对两者都使用 X-Hub-Signature-256 进行签名。
easyCoexistence 会将每个已连接粉丝专页的 Messenger 消息与提及,一到达即转发到您的 HTTPS 端点,使用该粉丝专页专属的密钥签名,且不保留副本;send_social_dm 可在 24 小时窗口内回复。
Meta 要求 Messenger Webhook 端点多快以 200 OK 响应每条通知。
若投递失败持续这么久,Meta 会取消应用对该粉丝专页 Webhook 的订阅,直到重新订阅为止。
messages 事件中的发送者粉丝专页范围 ID,对每个用户与粉丝专页的组合都是唯一的。
Meta 参考文档如何标注 mention 事件的 sender 字段。
过去的 Webhook 通知之后无法再查询,因此接收方必须自行存储所需内容。
messages 字段会发送什么?
当用户向粉丝专页发送 Messenger 消息时,系统会发出通知。Meta 会发送文本消息,或带附件的消息,附件类型包括图片、音频、视频、文件和贴纸等,分享的链接也可能以后备附件的形式到达。回复较早消息的消息会携带 reply_to,其值为该消息的 mid;快速回复则会携带其负载。
messages 事件是什么样的?
与动态变更不同,消息会放在粉丝专页 entry 内的 messaging 数组中到达。每个事件包含:sender,即用户的粉丝专页范围 ID;recipient,即粉丝专页;时间戳;以及 message,其中包含 mid 和 text,或包含 type 与负载 URL 的 attachments:
{
"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:
{
"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 分钟的时间戳。
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 作为键。
使用 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 监控
验证时间