Instagram message_reactions Webhook:react 與 unreact 負載
Instagram 的 message_reactions Webhook 欄位會在用戶於其與專業帳戶的對話中對訊息作出反應,或取消反應時,通知應用程式。該事件位於 messaging 陣列內,並附有 reaction 物件:mid 為所回應訊息的 ID;action 為 react 或 unreact;只有在 react 時,才會有 reaction(例如 love)與 emoji(表情符號本身)。
easyCoexistence 為每個已連接的 Instagram 帳戶訂閱 comments、messages 與 mentions,並在事件抵達時,以該帳戶的密鑰簽署後,連同每則訊息的 mid 轉發至你的 HTTPS 端點。
reaction.action 的兩個值:新增反應或移除反應。
Meta 自特定 Graph API 版本起,於此 webhook 支援 angry、sad、wow、love、like、laugh 及其他反應。
當帳戶本身對他人的訊息作出反應或取消反應時,Meta 不會發出通知。
message_reactions 是新 Instagram 產品在應用程式控制台中預設訂閱的欄位之一。
每個帳戶每秒的 Send API 呼叫次數,適用於文字、連結、反應與貼圖。
message_reactions 何時觸發?
當用戶在與專業帳戶的對話中對訊息作出反應,以及在移除該反應時,只要應用程式與帳戶已訂閱該欄位,便會觸發。Meta 的 Instagram 訊息指南對相反方向說得很清楚:當帳戶本身作出反應或取消反應時,不會發出通知,messages 也不會為此傳送 echo。
反應通知是什麼樣子?
一個 POST 請求,object 設為 instagram,其 entry 內含 messaging 陣列。與 DM 不同,此事件不含 message 物件:反應位於自己的 reaction 物件內,與 sender、recipient 及 timestamp 並列。以下是 Meta 為 Instagram Login 提供的範例:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"reaction": {
"mid": "<MESSAGE_ID>",
"action": "react",
"reaction": "love",
"emoji": "\u{2764}\u{FE0F}"
}
}
]
}
]
}各欄位的意義是什麼?
以下是 Meta 為反應事件記載的欄位,由外至內排列:
- entry[].id 與 recipient.id:專業帳戶。sender.id:作出反應者的 Instagram 範圍 ID。
- timestamp:事件觸發的時間,Meta 範例中以毫秒計;entry[].time 為 Meta 發送通知的時間。
- reaction.mid:所回應訊息的 ID,與該訊息在 messages 事件中的 mid 相同。
- reaction.action:新增反應時為 react,移除時為 unreact。
- reaction.reaction:反應的名稱,例如 love;Meta 列出 angry、sad、wow、love、like、laugh 及 other。
- reaction.emoji:以 Unicode 字串表示的表情符號,例如 love 的 \u{2764}\u{FE0F}。
- 取消反應(unreact)時,reaction 與 emoji 會被省略。
取消反應是什麼樣子?
與上述事件相同,但 action 設為 unreact,且沒有 reaction 與 emoji,因為已無可命名的內容。以 reaction.mid 與 sender.id 配對,找出它所移除的反應,並在你的紀錄中刪除該人在此訊息上的反應。
"reaction": {
"mid": "<MESSAGE_ID>",
"action": "unreact"
}mid 指向哪則訊息?
該用戶所回應的訊息,其 ID 與該訊息在 messages 事件中所帶的 mid 相同,包括帳戶自身訊息的 echo。若處理程式儲存 mid,便能把反應附加到對話的正確位置。Meta 指出一項限制:對輪播貼文中某張圖片的反應,會回報輪播的第一張圖片,未必是該用戶所選的那張。
帳戶如何對訊息作出反應?
使用 POST /<IG_ID>/messages:recipient.id 設為該用戶的 Instagram 範圍 ID,sender_action 設為 react,並在負載中帶上 message_id 與 reaction,reaction 可為表情符號或其 UTF-8 形式。以另一個表情符號重複呼叫即可更改反應;將 sender_action 設為 unreact 並只帶 message_id,則會移除反應。兩種呼叫都不會產生 webhook。
POST https://graph.instagram.com/<IG_ID>/messages
Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"recipient": { "id": "<IGSID>" },
"sender_action": "react",
"payload": {
"message_id": "<MESSAGE_ID>",
"reaction": "<EMOJI>"
}
}message_reactions 需要什麼?
使用 Instagram Login 時,需要 instagram_business_basic 與 instagram_business_manage_messages,若開發者並不擁有或管理該帳戶,則需 Advanced Access。新 Instagram 產品在應用程式控制台中預設訂閱 message_reactions,每個帳戶則透過 POST /<IG_ID>/subscribed_apps 訂閱。Meta 的 Send Messages 指南將其列為 messaging_reactions,但其欄位表、控制台預設值與 webhook 參考都寫作 message_reactions。
easyCoexistence 會轉發反應嗎?
不會。easyCoexistence 的應用程式及每個已連接的帳戶,只訂閱 comments、messages 與 mentions,因此 message_reactions 事件不會轉發至你的端點。反應以 mid 指向的 DM 與 echo 則會抵達端點,並以該帳戶的密鑰簽署。
常見錯誤
- 在 message 內尋找反應。反應事件沒有 message 物件,應讀取與 sender 及 recipient 並列的 reaction 物件。
- 未檢查 action 便讀取 reaction 或 emoji。取消反應時兩者都會被省略,因此假設它們存在的程式,會在反應被移除時出錯。
- 帳戶作出反應後等待 webhook。Meta 不會為帳戶自身的反應發送任何通知,連 echo 也沒有,因此應在應用程式發送反應時自行記錄。
- 照抄 Meta 的 Send Messages 指南中的 messaging_reactions 名稱。其欄位表、控制台預設值與 webhook 參考中的欄位名稱是 message_reactions。
你的 AI 代理會在 24 小時期限內,使用 send_social_dm 回覆用戶。每個連接每月 US$ 9 至 US$ 0.75,連接越多,單價越低,前 3 天免費。
常見問題
為何輪播貼文上的反應指向第一張圖片?
當有人對輪播中的某張圖片作出反應時,Meta 會回報輪播的第一張圖片,未必是該用戶所選的圖片。
帳戶作出反應時,Instagram 會發送 webhook 嗎?
不會。帳戶對訊息作出反應或取消反應時,Meta 既不發送 message_reactions 通知,也不發送 echo。
Instagram webhook 能回報哪些反應?
Meta 的 Instagram 訊息指南由 Graph API v12.0 起列出 angry、sad、wow、love、like、laugh 及其他反應,表情符號本身則位於 reaction.emoji 中。
webhook 欄位名稱是 message_reactions 還是 messaging_reactions?
是 message_reactions。Meta 的 Send Messages 指南寫作 messaging_reactions,但其欄位表、應用程式控制台預設值與 webhook 參考都使用 message_reactions。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期