Facebook 提及 Webhook:有人提及您的专页时
Facebook 专页 Webhook 的 mention 字段会在有人于帖子或评论中 @ 提及专页时通知应用。Meta 发送 field 设为 mention 的 change,其 value 可包含 post_id、评论的 comment_id、message 中的文本、附加的链接和媒体,以及 item 和 verb;请求为 POST,并以 X-Hub-Signature-256 签名。
easyCoexistence 会在您连接专页时,与 feed 和 messages 一起订阅 mention 字段,并在事件发生时将提及事件转发到您的 HTTPS 端点。
Facebook 专页 Webhook 中用于新提及的字段,包括评论和帖子中的提及。
专页管理员(具备 MODERATE 权限)必须授予的权限,专页 Webhook 才能送达应用的回调 URL。
用户在帖子或评论中提及专页的方法:输入 @ 和专页名称,然后选择。
Meta 对失败的专页通知进行重试的时长,频率递减,之后丢弃。
/{page-id}/tagged 边为每条被标记了专页的公开帖子添加的字段。
什么会触发提及 Webhook?
有人在帖子或评论中提及专页。在 Facebook 上,输入 @ 和专页名称并从建议中选择即为提及。Meta 的参考文档将该字段描述为专页的新提及,包括评论和帖子中的提及。Facebook 帮助中心指出,专页的设置可能会阻止他人提及它。
提及通知是什么样子?
一个 POST 请求,object 为 page,且包含一个 entry,代表被提及的专页:其 ID、时间,以及 field 为 mention 的 changes 数组。Meta 的参考文档列出了 value 的字段,但未提供示例,因此下面这个帖子中的提及是根据该列表构建的:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1793520000,
"changes": [
{
"field": "mention",
"value": {
"item": "post",
"verb": "add",
"post_id": "<POST_ID>",
"message": "<TEXT_WITH_THE_MENTION>"
}
}
]
}
]
}提及的各个字段是什么意思?
以下是 Meta 参考文档中 value 的字段;通知包含哪些字段取决于帖子或评论:
post_id:提及专页的帖子 ID。comment_id:评论的 ID,当提及位于评论中时;parent_id:其父级的 ID。- message:包含提及的文本。
- link、photo、photos 和 video:帖子或评论所附内容的链接。
- item 和 verb:对象的类型以及对其所做的操作,取自 feed 字段使用的同一列表。
created_time:帖子或评论的创建时间。- from 和
message_tags:发布者以及文本中被标记的个人资料,两者均仅限 Workplace 使用。 - 另外列出:action、
album_id、event_id、photo_id、video_id、share_id、published、reaction_type、recipient_id和open_graph_story_id。
提及字段需要哪项权限?
pages_manage_metadata。Meta 要求具备 MODERATE 权限的专页管理员授予该权限,专页 Webhook 才能送达应用。专页通过 POST /{page-id}/subscribed_apps 订阅,并在 subscribed_fields 中包含 mention,使用具备 CREATE_CONTENT、MANAGE 或 MODERATE 任务的人员提供的专页访问令牌,同时需要 pages_manage_metadata 和 pages_show_list。应用也要订阅 mention,因为只有在两个层级都订阅的字段才会送达;对于由应用中无角色人员管理的专页,这些权限需在 Advanced Access 中开通。
如何读取提及专页的帖子或评论?
通过其 ID 读取,在 Meta 允许的情况下使用专页访问令牌。专页访问令牌可读取发布到专页或由专页发布的帖子;其他专页公开分享的帖子需要 pages_manage_posts 权限和 Page Public Content Access 功能,并使用专页管理员的访问令牌;Meta 将读取个人帖子与该用户的 user_posts 权限相关联。
GET https://graph.facebook.com/<POST_ID>
?fields=message,permalink_url,created_time
&access_token=<PAGE_ACCESS_TOKEN>
GET https://graph.facebook.com/<COMMENT_ID>
?fields=message,from,created_time
&access_token=<PAGE_ACCESS_TOKEN>专页还能在哪里查找提及?
在 tagged 边上。GET /{page-id}/tagged 列出专页被标记的公开帖子,每条都带有 tagged_time,也涵盖在设置 Webhook 之前的帖子。它需要具备 CREATE_CONTENT、MANAGE 或 MODERATE 任务的人员提供的专页访问令牌,同时需要 pages_read_user_content 和 pages_show_list,Meta 表示可能需要 Page Public Content Access 功能。对于个人的帖子,Meta 仅向撰写者返回 from 字段。
easyCoexistence 如何转发提及事件?
专页连接时,它会与 feed 和 messages 一起订阅 mention。应用会在每次送达时校验 X-Hub-Signature-256,立即回复 Meta,并将该专页的每个 entry 原样 POST 到您通过 set_social_webhook_destination 或 Partner API 上的 PUT /channels/:id/webhook 设置的 HTTPS 端点:
- X-EC-Signature 携带 t=<unix>,v1=<hex>:即时间戳、一个点和原始正文的 HMAC-SHA256,以该专页的签名密钥为密钥。
- 密钥以 whsec_ 开头,仅显示一次;重新设置 URL 会签发新密钥,将 URL 设为 null 则停止转发。
- 每个 entry 仅发送一次,最多等待 8 秒,发送到解析为公网 IP 的 HTTPS 地址,不跟随重定向,也不保留副本。
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793520001,v1=<HEX_HMAC_SHA256>
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793520000,
"changes": [
{
"field": "mention",
"value": {
"item": "post",
"verb": "add",
"post_id": "<POST_ID>",
"message": "<TEXT_WITH_THE_MENTION>"
}
}
]
}
}常见错误
- 把 entry.time 当作提及发生的时间。Meta 将其设为通知发送的时刻;value 中的 created_time 才标注帖子或评论的创建时间。
- 把失败的查询当作事件故障。Meta 警告,提及通知中的部分 post_id 和 comment_id 因权限不足或隐私原因无法查询,因此应直接使用事件本身的消息文本。
- 在回复转发前抓取帖子。转发不会重试,因此应立即返回 2xx,之后再查询帖子。
事件使用该专页专属的密钥签名,且不保留副本,因此您的智能体能在每次提及发生时及时知晓。每个连接每月 US$ 9 至 US$ 0.75,随连接增加而降低,前 3 天免费试用。
常见问题
提及 Webhook 会说明是谁提及了专页吗?
对于专页,Meta 的参考文档将 from 标记为仅限 Workplace 使用。在 Meta 权限允许的情况下,通过 ID 查询帖子或评论可以返回其作者。
我能获取专页订阅之前的提及吗?
无法通过 Webhook 获取,因为 Meta 不保留可供查询的通知历史。tagged 边会列出专页被标记的公开帖子。
提及字段与 feed 有何不同?
feed 报告专页自身动态的变化,例如其中的帖子、评论和反应;mention 报告专页在帖子或评论中被 @ 提及。每个字段需单独订阅。
easyCoexistence 的评论规则会作用于提及吗?
不会。规则和自动化作用于来自 feed 字段的评论以及 Messenger 消息;提及变化会按照 Meta 发送的原样转发到您的端点。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间