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

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 端点。

mention

Facebook 专页 Webhook 中用于新提及的字段,包括评论和帖子中的提及。

pages_manage_metadata

专页管理员(具备 MODERATE 权限)必须授予的权限,专页 Webhook 才能送达应用的回调 URL。

@ + name

用户在帖子或评论中提及专页的方法:输入 @ 和专页名称,然后选择。

36 hours

Meta 对失败的专页通知进行重试的时长,频率递减,之后丢弃。

tagged_time

/{page-id}/tagged 边为每条被标记了专页的公开帖子添加的字段。

什么会触发提及 Webhook?

有人在帖子或评论中提及专页。在 Facebook 上,输入 @ 和专页名称并从建议中选择即为提及。Meta 的参考文档将该字段描述为专页的新提及,包括评论和帖子中的提及。Facebook 帮助中心指出,专页的设置可能会阻止他人提及它。

提及通知是什么样子?

一个 POST 请求,object 为 page,且包含一个 entry,代表被提及的专页:其 ID、时间,以及 field 为 mention 的 changes 数组。Meta 的参考文档列出了 value 的字段,但未提供示例,因此下面这个帖子中的提及是根据该列表构建的:

A mention in a post, from the fields in Meta's reference
{
  "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 权限相关联。

Looking up the post or the comment
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 地址,不跟随重定向,也不保留副本。
A forwarded mention, headers included
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,之后再查询帖子。
使用 EasyCoexistence 完成这些操作

事件使用该专页专属的密钥签名,且不保留副本,因此您的智能体能在每次提及发生时及时知晓。每个连接每月 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 监控

验证时间