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

Instagram messaging_postbacks Webhook:破冰问题和按钮

Instagram 的 messaging_postbacks Webhook 字段在用户点击专业账户会话中的破冰问题、模板中的 postback 按钮或持久菜单项时通知应用。事件中的 postback 对象包含 title(用户点击的文本)、payload(应用为该选项设置的字符串)以及 mid(消息 ID,自 Graph API v11.0 起提供)。

easyCoexistence 为每个已连接的 Instagram 账户订阅评论、消息和提及,并将这些事件(包括快速回复的点击)在到达时转发到您的 HTTPS 端点,使用该账户的密钥签名,且不保留任何副本。

4

账户通过 Meta 的 Ice Breaker API 最多可设置的破冰问题数量。

v11.0

postback 事件开始包含 mid 的 Graph API 版本;该字段本身需要 v8.0 或更高版本。

3

按钮模板消息中最多可放置的按钮数,每个按钮为 postback 或 web_url 类型。

24 hours

用户点击持久菜单项后的响应时限,该操作会打开标准消息窗口。

13

单条消息可提供的快速回复数量上限;被点击的快速回复以 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。通知如下所示:

A messaging_postbacks notification, as Meta sends it
{
  "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 返回的值。

Setting two ice breakers
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 个问题,且该功能在桌面端不可用。
使用 EasyCoexistence 完成这些操作

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 监控

验证时间