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 端点,使用该账户自己的密钥签名。
App Dashboard 中新建的 Instagram 产品默认订阅的字段,其中包括 comments、messages 和 message_reactions。
字段按应用而非按账户选择:账户会收到应用所选的字段。
Meta 设置指南对 Instagram Login Webhook 所列的访问级别,comments 和 live_comments 通知要求此级别。
Meta 字段表将某字段标注为 Instagram Login 不可用,但该字段通过 Facebook Login 和 Unified Login 提供。
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。
哪些字段在 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 中选择的字段,并以逗号分隔。
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 的指标。
事件默认不予存储;开启自动化的账户会将其私信和评论保留 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 监控
验证时间