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

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 端點,以該帳戶的密鑰簽章。

8

在應用程式控制台新建 Instagram 產品時,預設訂閱的欄位包括 comments、messages 與 message_reactions。

Per app

欄位是按應用程式選定的,而非按帳戶逐一設定:帳戶會收到應用程式所選的欄位。

Advanced Access

Meta 設定指南為 Instagram Login webhook 列出的存取級別,comments 與 live_comments 通知須具備此級別。

story_insights

Meta 欄位表標示該欄位不適用於 Instagram Login,但在 Facebook Login 與 Unified Login 下提供。

10 Sep 2025

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。

commentsA comment or reply on the account's posts, Reels, Stories or ads, @mentions included. instagram_business_manage_comments.
live_commentsA comment on the account's Live while it is broadcast. instagram_business_manage_comments.
mentionsNo field of its own with Instagram Login: Meta includes mentions in the comments notification.
messagesA DM: text, attachments, shares, Story replies and mentions, quick replies, deletions, and echoes of the account's own messages. instagram_business_manage_messages.
message_echoesListed with instagram_business_manage_comments; the account's own messages arrive on messages with is_echo set to true.
message_reactionsA person reacts to a message or removes the reaction. instagram_business_manage_messages.
message_editA person edits a message, with mid, text and num_edit. In Meta's examples and changelog, not in its fields table.
messaging_postbacksA tap on an ice breaker, a template's postback button or a persistent menu item. instagram_business_manage_messages.
messaging_referralAn ig.me link with a ref parameter, opened in an existing conversation. instagram_business_manage_messages.
messaging_seenA person reads a message, reported as read.mid. instagram_business_manage_messages.
messaging_optinsListed with instagram_business_manage_messages; Meta's Instagram examples show no payload for it.
messaging_handoverThread control passed, taken or requested between apps under the handover protocol. instagram_business_manage_messages.
standbyA message that arrives while another app controls the conversation. instagram_business_manage_messages.

哪些欄位不適用於 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 設為控制台所選的欄位,以逗號分隔。

Subscribing one account to three 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 在此標示為不可用,因此應趁限時動態仍在時,從洞察端點讀取其指標。
使用 EasyCoexistence 完成這項設定

事件預設不儲存;開啟自動化的帳戶會將其私訊及留言保留 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 監察

驗證日期