Instagram messaging_postbacks Webhook:破冰問題與按鈕
當用戶在與專業帳戶的對話中點按破冰問題、範本中的 postback 按鈕或持久選單項目時,Instagram 的 messaging_postbacks Webhook 欄位會通知應用程式。事件的 postback 物件包含 title(用戶點按的文字)、payload(應用程式為該選項設定的字串),以及自 Graph API v11.0 起提供的 mid(訊息 ID)。
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 個,通用範本每個元素最多 3 個。
- 帳戶持久選單中的 postback 項目。
- 透過帶有 ref 參數的 ig.me 連結開啟的新對話中,點按的破冰問題;此時 postback 同時會包含 referral。
- 自我傳訊測試,即帳戶點按自己的按鈕:事件會加入值為 true 的
is_self。
postback 通知是什麼樣子?
事件中原本放置訊息的位置,會是一個 postback 物件。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 組問題與 payload 配對,每個已翻譯的版本可附上 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 個按鈕。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 個問題,且此功能不支援桌面版。
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 監察
驗證日期