Instagram messaging_postbacks Webhook:破冰问题和按钮
Instagram 的 messaging_postbacks Webhook 字段在用户点击专业账户会话中的破冰问题、模板中的 postback 按钮或持久菜单项时通知应用。事件中的 postback 对象包含 title(用户点击的文本)、payload(应用为该选项设置的字符串)以及 mid(消息 ID,自 Graph API v11.0 起提供)。
easyCoexistence 为每个已连接的 Instagram 账户订阅评论、消息和提及,并将这些事件(包括快速回复的点击)在到达时转发到您的 HTTPS 端点,使用该账户的密钥签名,且不保留任何副本。
账户通过 Meta 的 Ice Breaker API 最多可设置的破冰问题数量。
postback 事件开始包含 mid 的 Graph API 版本;该字段本身需要 v8.0 或更高版本。
按钮模板消息中最多可放置的按钮数,每个按钮为 postback 或 web_url 类型。
用户点击持久菜单项后的响应时限,该操作会打开标准消息窗口。
单条消息可提供的快速回复数量上限;被点击的快速回复以 messages 形式到达,而不是 messaging_postbacks。
messaging_postbacks 何时触发?
当用户在会话中点击账户的某个结构化选项,且应用和账户都已订阅该字段时触发。Meta 的指南列出了以下来源:
- 破冰问题:会话开始时账户最多可提供 4 个破冰问题。桌面端不支持。
- 按钮模板中的 postback 按钮,每条消息最多 3 个;或通用模板中的 postback 按钮,每个元素最多 3 个。
- 账户持久菜单中的 postback 项。
- 通过带 ref 参数的 ig.me 链接打开的新会话中被点击的破冰问题:此时 postback 还会包含 referral。
- 自我发消息测试:账户点击自己的按钮时,事件会添加值为 true 的
is_self。
postback 通知是什么样子?
在原本是 DM 消息的位置,会出现包含 postback 对象的 messaging 事件。Meta 为 Instagram Login 提供的示例包含 mid、title 和 payload,其破冰问题指南展示的同一对象则不含 mid。通知如下所示:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}各字段的含义是什么?
Meta 为 postback 记录的字段,从外到内依次为:
- sender.id:点击者的 Instagram 范围 ID,即回复的目标 ID。recipient.id 和 entry[].id:专业账户。
- timestamp:用户点击的时间,依据 Meta 的破冰问题指南。
- postback.title:用户看到的破冰问题或按钮标题。
- postback.payload:创建该选项时设置的字符串,由应用自行选择。
- postback.mid:点击操作发送到账户的消息 ID,自 Graph API v11.0 起提供。
- postback.referral:ref、source 和 type,当会话通过带 ref 参数的 ig.me 链接打开时提供。
is_self:与 postback 并列设置为 true,表示账户在自我发消息测试中点击了自己的按钮。
如何设置破冰问题?
向 graph.instagram.com 发送 POST /<IG_ID>/messenger_profile,其中 platform 设为 instagram,ice_breakers 数组的 call_to_actions 包含最多 4 组问题与负载的配对,每组翻译版本可附带 locale(语言区域)。GET /me/messenger_profile?fields=ice_breakers 可列出这些设置,将 fields 设为 ice_breakers 的 DELETE 请求则可将其删除。此处设置的负载即为用户点击该问题时 messaging_postbacks 返回的值。
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}如何发送 postback 按钮?
在账户通过 POST /<IG_ID>/messages 发送的消息中添加。按钮模板的文本最多 640 个字符,并包含 1 至 3 个按钮;通用模板最多 10 个元素,每个元素最多 3 个按钮。类型为 postback 的按钮被点击时,会在 messaging_postbacks 中返回其负载;web_url 按钮则会在应用内浏览器中打开页面。持久菜单在 messenger_profile 上设置,同样支持这两种类型。
快速回复是否使用 messaging_postbacks?
否:快速回复会在 messages 中到达。被点击的快速回复会以文本形式把其标题发到会话中,messages 事件的 text 为该标题,quick_reply.payload 为该选项的负载。单条消息最多可提供 13 个快速回复,每个最多 20 个字符,仅限纯文本。Meta 的 Instagram 消息指南也列出了破冰问题和通用模板的选择会出现在 messages 中,但未提供示例负载。
点击是否会打开消息窗口?
对于持久菜单,Meta 明确说明:点击菜单项会打开标准消息窗口,账户有 24 小时的响应时间。使用 POST /<IG_ID>/messages 回复,并将 recipient.id 设为 postback 的 sender.id。账户的回复会在 messages 中以 echo 形式返回,且 is_echo 为 true。
easyCoexistence 是否转发 postback?
只包括快速回复的点击。这些点击会在 messages 中到达,而 easyCoexistence 的应用及每个已连接账户均已订阅该字段,因此会连同 quick_reply.payload 送达您的端点。破冰问题、按钮和菜单的点击则在 messaging_postbacks 中到达,easyCoexistence 未订阅该字段,因此不会转发。
常见错误
- 在 messaging_postbacks 中等待快速回复。快速回复会在 messages 中到达,其中 text 为被点击选项的文本,并附带 quick_reply.payload。
- 根据 postback.title 路由。title 是用户看到的文本,可能因语言区域而不同;应根据应用设置的 payload 路由。
- 在旧版 API 中期待 mid。Meta 仅从 Graph API v11.0 起才包含 postback.mid。
- 设置超过 4 个破冰问题,或在桌面端测试。Meta 的 Ice Breaker API 最多接受 4 个问题,且该功能在桌面端不可用。
send_social_dm 可在 24 小时窗口内回复用户。每个连接每月 US$ 9 起,随连接数增加降至 US$ 0.75,前 3 天免费。
常见问题
哪个 Webhook 字段会报告 Instagram 破冰问题的点击?
messaging_postbacks。postback 对象包含以 title 表示的问题,以及为其设置的 payload,还有自 Graph API v11.0 起提供的 mid。
一个 Instagram 账户可以有多少个破冰问题?
最多 4 个问题,通过 POST /<IG_ID>/messenger_profile 设置,platform 设为 instagram,可按语言区域分别设置。
如何回复 Instagram 的 postback?
使用 POST /<IG_ID>/messages,并将 recipient.id 设为 postback 的 sender.id,即点击者的 Instagram 范围 ID。点击持久菜单后,Meta 允许账户在 24 小时内回复。
应根据 title 还是 payload 路由 Instagram postback?
根据 payload,即应用为该选项设置的字符串。title 是用户看到的文本,可能因语言区域而异。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间