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,提及則包含於 comments 之中;其範例另外列出 message_edit。每個欄位都需要 instagram_business_basic,另加 instagram_business_manage_comments;大多數訊息欄位則需要 instagram_business_manage_messages。story_insights 不適用於 Instagram Login。
easyCoexistence 為每個已連接的 Instagram 帳戶訂閱 comments、messages 與 mentions,並在事件到達時將其轉發至你的 HTTPS 端點,以該帳戶的密鑰簽章。
在應用程式控制台新建 Instagram 產品時,預設訂閱的欄位包括 comments、messages 與 message_reactions。
欄位是按應用程式選定的,而非按帳戶逐一設定:帳戶會收到應用程式所選的欄位。
Meta 設定指南為 Instagram Login webhook 列出的存取級別,comments 與 live_comments 通知須具備此級別。
Meta 欄位表標示該欄位不適用於 Instagram Login,但在 Facebook Login 與 Unified Login 下提供。
Meta 為 Business Login for Instagram 及 Facebook Login for Business 推出 message_edit webhook 的時點。
Instagram Login 提供哪些 webhook 欄位?
以下為 Meta 欄位表所列的欄位,各欄位的觸發條件取自其範例與 webhook 參考文件。每個欄位除所示權限外,還需要 instagram_business_basic;Meta 要求 comments 與 live_comments 通知須具備 Advanced Access。
哪些欄位不適用於 Instagram Login?
Meta 欄位表中有三列不具備 Instagram Login 權限,因此以 Instagram Login 運作的應用程式不會收到這些欄位;另有一個欄位只存在於該範圍之外:
story_insights:限時動態到期時的指標,需要 Facebook Login 或 Unified Login 以及instagram_manage_insights。Meta 的媒體洞察參考文件指出,Instagram Login 不支援洞察 webhook。messaging_policy_enforcement與response_feedback:僅列於 Meta 的 Instagram Messaging API 一欄。- 獨立作為欄位的 mentions:Facebook Login 與 Unified Login 列出此欄位,並需要
instagram_manage_comments;Instagram Login 則將提及併入 comments。
如何訂閱欄位?
分兩處進行。在應用程式控制台的 Instagram 產品 webhook 設定中,儲存回調 URL 與驗證權杖,以觸發 Meta 的驗證請求,然後選取欄位;新建的 Instagram 產品預設訂閱其中八個欄位。接著,在 graph.instagram.com 上對每個帳戶呼叫 POST /<IG_ID>/subscribed_apps,並將 subscribed_fields 設為控制台所選的欄位,以逗號分隔。
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 應列出控制台所選的欄位,因此處理程式應預期應用程式所選的任何欄位,並依每個事件所含的內容判斷,而非依其為某個帳戶所要求的內容。
如何在通知中分辨各欄位?
依項目的結構分辨。留言類欄位以 changes 陣列傳送,每個變更均標明其欄位。訊息類欄位以 messaging 陣列傳送,且不含欄位名稱;sender、recipient 與 timestamp 旁的鍵可用來區分:
- changes[].field:comments 或
live_comments,留言內容位於 value 中。 - message:messages,包括帳戶自身訊息的回音,這些回音的
is_echo設為 true。 - 反應:
message_reactions。postback:messaging_postbacks。已讀:messaging_seen。編輯: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 之中,因此訂閱涵蓋留言與私訊,私訊中包括回音、限時動態回覆、限時動態提及與附件。表中其他欄位由 Meta 傳送給已訂閱它們的應用程式,不屬於連接的訂閱範圍。透過 set_social_webhook_destination 或 Partner API 設定端點後,easyCoexistence 會核對 Meta 的簽章、立即回覆 Meta,並將該帳戶的每個項目以 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 欄位為鍵的處理程式永遠不會執行。
- 以為帳戶只會收到其自身訂閱所指定的欄位。Meta 會傳送應用程式所選的欄位,因此應依每個事件所含的內容分支處理。
- 將 message.referral 與頂層 referral 視為同一個事件。前者屬於 messages;後者為 messaging_referral,用於在既有對話中開啟的 ig.me 連結。
- 在 Instagram Login 下等待 story_insights。Meta 在此標示為不可用,因此應趁限時動態仍在時,從洞察端點讀取其指標。
事件預設不儲存;開啟自動化的帳戶會將其私訊及留言保留 7 天。可透過 Claude 或 ChatGPT 使用 set_social_webhook_destination,或透過 Partner API 設定端點。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,前 3 天免費試用。
常見問題
Instagram Login 有獨立的 mentions webhook 欄位嗎?
沒有獨立的欄位。Meta 在 Instagram Login 下將 mentions 併入 comments 通知;mentions 則是 Facebook Login 與 Unified Login 下的獨立欄位。
story_insights 可用於 Instagram Login 嗎?
不可用。Meta 欄位表標示此欄位不適用於 Instagram Login,其媒體洞察參考文件亦指出,該處不支援洞察 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 監察
驗證日期