登入開始免費試用
easyCoexistence 官方 API

Instagram messaging_postbacks Webhook:破冰問題與按鈕

當用戶在與專業帳戶的對話中點按破冰問題、範本中的 postback 按鈕或持久選單項目時,Instagram 的 messaging_postbacks Webhook 欄位會通知應用程式。事件的 postback 物件包含 title(用戶點按的文字)、payload(應用程式為該選項設定的字串),以及自 Graph API v11.0 起提供的 mid(訊息 ID)。

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 個,通用範本每個元素最多 3 個。
  • 帳戶持久選單中的 postback 項目。
  • 透過帶有 ref 參數的 ig.me 連結開啟的新對話中,點按的破冰問題;此時 postback 同時會包含 referral。
  • 自我傳訊測試,即帳戶點按自己的按鈕:事件會加入值為 true 的 is_self。

postback 通知是什麼樣子?

事件中原本放置訊息的位置,會是一個 postback 物件。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 組問題與 payload 配對,每個已翻譯的版本可附上 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 個按鈕。type 為 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。帳戶的回覆會以 is_echo 設為 true 的回聲(echo)形式,回傳到 messages。

easyCoexistence 會轉發 postback 嗎?

只有快速回覆的點按。它們透過 messages 送達,而 easyCoexistence 的應用程式及每個已連接的帳戶均已訂閱 messages,因此會連同 quick_reply.payload 送到你的端點。破冰問題、按鈕及選單的點按則透過 messaging_postbacks 送達,easyCoexistence 並未訂閱該欄位,因此不會轉發。

常見錯誤

  • 等待快速回覆出現在 messaging_postbacks。快速回覆會透過 messages 送達,其 quick_reply.payload 與被點按選項的文字一同出現。
  • 依 postback.title 進行路由。title 是用戶所見的內容,可能因語言地區而異;應依應用程式設定的負載進行路由。
  • 在較舊的 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 記錄問題,並附上為其設定的負載,以及自 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 小時回覆。

Instagram postback 應依 title 還是負載進行路由?

應依負載進行路由,即應用程式為選項設定的字串。title 是用戶所見的文字,可能因語言地區而異。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期