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

Instagram Webhook 字段:完整列表

对于使用 Instagram Login 的专业账户,Meta 的 Webhook 字段表列出了 comments、live_comments、messages、message_echoes、message_reactions、messaging_postbacks、messaging_referral、messaging_seen、messaging_optins、messaging_handover 和 standby,其中 mentions 随 comments 一并送达;其示例还包括 message_edit。每个字段都需要 instagram_business_basic,另加 instagram_business_manage_comments;大多数消息类字段则需要 instagram_business_manage_messages。Instagram Login 不提供 story_insights。

easyCoexistence 为每个已连接的 Instagram 账户订阅 comments、messages 和 mentions,并在事件到达时将其转发至您的 HTTPS 端点,使用该账户自己的密钥签名。

8

App Dashboard 中新建的 Instagram 产品默认订阅的字段,其中包括 comments、messages 和 message_reactions。

Per app

字段按应用而非按账户选择:账户会收到应用所选的字段。

Advanced Access

Meta 设置指南对 Instagram Login Webhook 所列的访问级别,comments 和 live_comments 通知要求此级别。

story_insights

Meta 字段表将某字段标注为 Instagram Login 不可用,但该字段通过 Facebook Login 和 Unified Login 提供。

10 Sep 2025

Meta 推出 message_edit Webhook 的时间:面向 Business Login for Instagram 与 Facebook Login for Business。

Instagram Login 提供哪些 Webhook 字段?

以下字段摘自 Meta 的字段表,每个字段的触发条件取自其示例和 Webhook 参考文档。每个字段除所示权限外,还需要 instagram_business_basic;Meta 要求 comments 和 live_comments 通知使用 Advanced Access。

commentsA comment or reply on the account's posts, Reels, Stories or ads, @mentions included. instagram_business_manage_comments.
live_commentsA comment on the account's Live while it is broadcast. instagram_business_manage_comments.
mentionsNo field of its own with Instagram Login: Meta includes mentions in the comments notification.
messagesA DM: text, attachments, shares, Story replies and mentions, quick replies, deletions, and echoes of the account's own messages. instagram_business_manage_messages.
message_echoesListed with instagram_business_manage_comments; the account's own messages arrive on messages with is_echo set to true.
message_reactionsA person reacts to a message or removes the reaction. instagram_business_manage_messages.
message_editA person edits a message, with mid, text and num_edit. In Meta's examples and changelog, not in its fields table.
messaging_postbacksA tap on an ice breaker, a template's postback button or a persistent menu item. instagram_business_manage_messages.
messaging_referralAn ig.me link with a ref parameter, opened in an existing conversation. instagram_business_manage_messages.
messaging_seenA person reads a message, reported as read.mid. instagram_business_manage_messages.
messaging_optinsListed with instagram_business_manage_messages; Meta's Instagram examples show no payload for it.
messaging_handoverThread control passed, taken or requested between apps under the handover protocol. instagram_business_manage_messages.
standbyA message that arrives while another app controls the conversation. instagram_business_manage_messages.

哪些字段在 Instagram Login 下不可用?

Meta 字段表中有三行没有 Instagram Login 权限,因此使用 Instagram Login 的应用不会收到这些字段;另有一个字段仅存在于该登录方式之外:

  • story_insights:Story 过期时的指标,需要 Facebook Login 或 Unified Login 以及 instagram_manage_insights。Meta 的媒体洞察参考文档指出,Instagram Login 不支持 insights Webhook。
  • messaging_policy_enforcement 和 response_feedback:仅出现在 Meta Instagram Messaging API 的列中。
  • 作为独立字段的 mentions:Facebook Login 和 Unified Login 将其列为独立字段,需要 instagram_manage_comments;而 Instagram Login 则将 mentions 并入 comments。

如何订阅字段?

分两处完成。在 App Dashboard 中,于 Instagram 产品的 Webhook 设置下保存回调 URL 和验证令牌,这将触发 Meta 的验证请求,然后选择字段;新建的 Instagram 产品默认订阅其中 8 个字段。然后,通过 graph.instagram.com 上的 POST /<IG_ID>/subscribed_apps 为每个账户订阅,将 subscribed_fields 设为在 Dashboard 中选择的字段,并以逗号分隔。

Subscribing one account to three fields
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages,message_reactions
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

每个账户能否获得不同的字段?

不能。Meta 的设置指南指出,无法为每个应用用户的账户单独选择字段:账户会收到为应用选择的字段。账户订阅中的 subscribed_fields 应列出 Dashboard 中的字段,因此处理程序应预期应用所选的任何字段,并根据每个事件所含内容进行判断,而非根据它为某个账户请求了什么。

如何在通知中区分字段?

通过 entry 的结构区分。评论类字段在 changes 数组中送达,每个 change 注明其字段。消息类字段在 messaging 数组中送达,没有字段名;sender、recipient 和 timestamp 旁边的键用于区分它们:

  • changes[].field:comments 或 live_comments,评论内容位于 value 中。
  • message:messages,包括账户自身消息的回显,回显的 is_echo 设为 true。
  • reaction:message_reactions。postback:messaging_postbacks。read:messaging_seen。message_edit:message_edit。
  • 与 sender 并列的 referral:messaging_referral。message 内的 referral 属于 messages,来自新会话或 Click-to-Direct 广告。
  • pass_thread_control、take_thread_control 或 request_thread_control:messaging_handover,如 Meta 的 Webhook 参考文档所列。

easyCoexistence 订阅哪些字段?

comments、messages 和 mentions,这是每个 Instagram 账户连接时订阅的列表。在 Instagram Login 下,mentions 包含在 comments 中,因此订阅覆盖 comments 和私信,其中私信包括回显、Story 回复、Story 提及和附件。表中的其他字段由 Meta 投递给订阅了这些字段的应用,不属于连接的订阅范围。通过 set_social_webhook_destination 或 Partner API 设置端点后,easyCoexistence 会验证 Meta 的签名,立即回应 Meta,并将该账户的每个 entry POST 到该端点:

  • platform 和 external_id:instagram,以及账户的 Instagram ID,与 entry.id 相同。
  • account_id:该连接在 easyCoexistence 中的 ID,即 MCP 工具所使用的 ID。
  • entry:Meta 为该账户提供的 entry,保持原样。Meta 的 object 字段和其 X-Hub-Signature-256 标头不会被转发。
  • X-EC-Signature:t=<unix>,v1=<hex>,即对时间戳、点号(.)和原始请求体进行的 HMAC-SHA256 计算,密钥为该账户自有的密钥。
  • 投递:单次尝试,超时时间最长 8 秒,不跟随重定向,不保留副本,也不重试。

常见错误

  • 在 Instagram Login 下等待 mentions 字段。Meta 将 mentions 并入 comments 通知,因此以 mentions 字段为键的处理程序永远不会运行。
  • 以为账户只会收到其自身订阅所指定的字段。Meta 投递的是为应用选择的字段,因此应根据每个事件所含内容进行分支处理。
  • 将 message.referral 与顶层 referral 视为同一事件。前者随 messages 送达;后者为 messaging_referral,适用于在现有会话中打开的 ig.me 链接。
  • 在 Instagram Login 下等待 story_insights。Meta 已将其标注为不可用,因此应在端点仍可用期间,通过 insights 端点读取 Story 的指标。
使用 EasyCoexistence 完成这些操作

事件默认不予存储;开启自动化的账户会将其私信和评论保留 7 天。您可以通过 Claude 或 ChatGPT 中的 set_social_webhook_destination,或通过 Partner API 设置端点。每个连接每月 US$ 9 起,连接越多越便宜,最低降至 US$ 0.75,前 3 天免费试用。

常见问题

Instagram Login 有独立的 mentions Webhook 字段吗?

没有独立字段。Meta 在 Instagram Login 的 comments 通知中包含 mentions;mentions 是 Facebook Login 和 Unified Login 下的独立字段。

Instagram Login 能使用 story_insights 吗?

不能。Meta 的字段表将其标注为 Instagram Login 不可用,其媒体洞察参考文档也指出该处不支持 insights Webhook。

Instagram 消息 Webhook 需要哪些权限?

instagram_business_basic 和 instagram_business_manage_messages,并需要 Advanced Access,这是 Meta 设置指南对 Instagram Login Webhook 的要求。

Meta 何时为 Instagram 添加 message_edit Webhook?

2025 年 9 月 10 日,面向 Business Login for Instagram 和 Facebook Login for Business。编辑内容在 messaging 数组中以 message_edit 键送达。

继续阅读

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

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

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

验证时间