Instagram 訊息 Webhook:私訊負載、回聲與欄位
Instagram 訊息 Webhook 欄位會把專業帳戶的私訊即時送出:文字、附件、分享內容、限時動態回覆與提及、內嵌回覆及刪除事件。每個事件都位於 messaging 陣列中,包含發送者的 Instagram 範圍 ID、接收者、時間戳記與 message 物件;帳戶自己發出的訊息會以 is_echo 設為 true 的形式,回傳到同一欄位。
easyCoexistence 為每個已連接的 Instagram 帳戶訂閱 messages,並把其私訊(包括回聲)在抵達時轉發到你的 HTTPS 端點,以該帳戶的密鑰簽署;轉發不保留副本,私訊預設亦不儲存。
在訊息事件上設為 true,代表該訊息由帳戶自己發出。
大多數用戶操作適用的標準訊息時段,期間應用程式可以回覆該用戶。
分享貼文的附件類型;舊的 share 類型只支援至 2026 年 2 月 1 日。
有人在限時動態中提及帳戶時,Meta 發送的私訊事件所用的附件類型。
帳戶擁有者停用 Instagram 私訊存取時,代碼 200 下的錯誤子代碼。
messages 欄位何時觸發?
當用戶發私訊給專業帳戶,以及帳戶發出私訊時觸發。Meta 的範例與參考資料列出以下情況,每一種都是帶有 message 物件的 messaging 事件:
- 文字,以及以附件形式傳送的媒體:圖片、影片、音訊與檔案。
- 分享的貼文或 Reel,以
ig_post、ig_reel或 reel 附件形式傳送。 - 對帳戶限時動態的回覆,以
reply_to.story 表示;提及帳戶的限時動態,以story_mention附件表示。 - 內嵌回覆早前的訊息(
reply_to.mid),以及快速回覆(quick_reply.payload)。 - 用戶刪除的訊息(
is_deleted)、不支援的媒體(is_unsupported),以及來自 Click-to-Direct 廣告點擊者的訊息(referral)。 - 帳戶發出的訊息,會以
is_echo設為 true 回傳。
訊息通知是什麼樣子?
一個 POST 請求,其 JSON 的 object 設為 instagram。與留言不同,訊息位於帳戶 entry 內的 messaging 陣列中,每個元素都包含 sender、recipient、timestamp 與 message。以下是對帳戶限時動態的回覆範例:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}每個欄位代表什麼?
以下是 Meta 在 Instagram Login 下為訊息事件記錄的欄位,由外至內排列:
- entry[].id:專業帳戶的 ID。entry[].time:Meta 發出通知的時間,Meta 的訊息範例以毫秒表示。
- sender.id 與 recipient.id:收到私訊時,分別為用戶的 Instagram 範圍 ID 與帳戶的 ID;回聲時則對調。
- timestamp:訊息發出的時間,Meta 範例以毫秒表示。請按此排序,而非按抵達次序排序。
- message.mid:訊息 ID,用於去重、表情回應,以及以
reply_to.mid 回覆該訊息。 - message.text:訊息含文字時才會包含。
- message.attachments[]:每項都有 type 與 payload,通常包含 url。分享貼文的
ig_postpayload 會加入ig_post_media_id與 title(即其說明文字)。 - message.
reply_to:內嵌回覆為 mid;限時動態回覆則為 story,包含限時動態的 url 與 id。 - message.
quick_reply.payload 與 message.referral:所選的快速回覆,以及 Click-to-Direct 廣告的 ref、ad_id、source、type 與ads_context_data。 - message.
is_deleted、is_echo、is_self與is_unsupported:只在為 true 時才包含。 - message.
admin_text與handoff_reason:在符合資格的應用程式上,表示 Meta 應用程式(例如 Meta Business Agent)已將對話轉交的通知;可能沒有 mid 或文字。
回聲如何運作?
帳戶發出訊息時,Meta 同樣會為此發送訊息事件,並將 is_echo 設為 true。此時 sender.id 為帳戶,recipient.id 為用戶的 Instagram 範圍 ID;帳戶發給自己的測試訊息亦會帶有 is_self。回聲記錄了帳戶的發言,對話紀錄需要它;但決定是否回覆的處理程序必須略過回聲。帳戶對訊息作出表情回應或移除回應時,Meta 不會發出回聲。
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}應該回覆哪個 ID?
sender.id,即用戶的 Instagram 範圍 ID。用戶向帳戶發訊息或在其媒體留言時,Meta 會建立此 ID,它只屬於該用戶與該帳戶。以 recipient.id 設為此 ID 呼叫 POST /<IG_ID>/messages 即可發出回覆。事件不包含名稱或用戶名稱;呼叫 GET /<IGSID> 並指定 name 與 username 等欄位即可取得,因為曾向帳戶發訊息的用戶已給予該查詢所需的同意。
私訊如何開啟 24 小時時段?
應用程式只能在用戶先向帳戶發訊息後,並且只能在該行為所開啟的標準訊息時段內,向用戶發訊息。大多數行為的時段為 24 小時;由點擊 Click-to-Direct 廣告後發出的第一則訊息,最長可達 7 天。用戶的新訊息會開啟新的時段,因此應追蹤其最新的 timestamp;回聲屬於帳戶自己發出的訊息,不會延長任何時段。用戶撰寫的回覆可以使用 Meta 獨立的 7 天 Human Agent 時段,並以 human_agent 標記。
訊息事件不包含什麼?
根據 Meta 的訊息參考資料,處理程序可能會尋找的一些資料並不包含在內:
- 用戶的名稱或用戶名稱:只有 Instagram 範圍 ID,可透過 GET /<IGSID> 解析。
- 只能觀看一次的媒體:以不含 URL 的暫時附件形式抵達。
- 確切的輪播圖片:對輪播貼文中某張圖片的表情回應或轉寄,只會回報第一張圖片。
- 表情回應、編輯與已讀回條:它們位於各自的欄位中。
- 已讀標記:透過 webhook 送達的訊息,在傳送回覆之前,會在 Instagram 收件匣中保持未讀。
Meta 還列出哪些其他訊息欄位?
Meta 在 Instagram Login 下的欄位清單與範例,除 messages 外還列出以下各項,每項都是獨立的訊息事件。easyCoexistence 只為每個帳戶訂閱 messages、comments 與 mentions,因此以下各項都不在其轉發的內容之中:
message_reactions:用戶對訊息作出表情回應或移除回應,包含 reaction.mid、action(設為 react 或 unreact),以及 reaction 與 emoji。message_edit:用戶編輯訊息,包含message_edit.mid、新文字與num_edit。messaging_postbacks:用戶點選破冰提示或範本按鈕,包含 postback.mid、title 與 payload。messaging_referral:已在對話中的用戶開啟附有 ref 參數的 ig.me 連結。messaging_seen:用戶閱讀訊息,包含 read.mid。messaging_optins、messaging_handover與 standby:後兩者適用於根據 Meta 交接協議共用對話的應用程式。
帳戶必須開啟什麼?
「允許存取訊息」。Meta 要求專業帳戶先開啟此設定,才能透過 API 管理其訊息:在 Instagram 應用程式中前往「設定」、「訊息和限時動態回覆」、「訊息控制」、「已連接的工具」。關閉時,發送會以代碼 200、子代碼 2534041 失敗。應用程式亦需要 instagram_business_basic 與 instagram_business_manage_messages;如要服務並非由其擁有或管理的帳戶,則需要 Advanced Access。
easyCoexistence 如何轉發私訊?
與留言相同:Meta 為帳戶發送的每個 entry,都會以 platform、account_id、external_id 與 entry 組成的信封,POST 到你的 HTTPS 端點。信封以 X-EC-Signature 簽署,使用該帳戶的密鑰,每則只發送一次,不保留副本。回聲與其他內容一同轉發,因此回覆前請先檢查 is_echo。如需回覆,請呼叫 send_social_dm,帶入 account_id,並將事件的 sender.id 作為 recipient_id,且須在 24 小時時段內。以私訊觸發的自動化,會在同一批事件上運行。
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}常見錯誤
- 回覆回聲。is_echo 已設定的事件是帳戶自己的訊息,回覆它會令帳戶與自己形成循環。
- 假設訊息一定含有文字。附件、分享內容、限時動態提及與刪除,抵達時都不含 text 欄位,因此應按 message 物件中的內容分支處理。
- 按抵達次序排列訊息。Meta 在故障後可能亂序送達訊息,因此應按 timestamp 排序。
- 把 time 與 timestamp 當作秒解析。Meta 的訊息範例兩者都以毫秒表示;若當作秒讀取,會變成遙遠未來的日期。
send_social_dm 在 24 小時時段內回覆,自動化可按固定文字或 AI 自行回覆。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,前 3 天免費。
常見問題
Instagram 訊息 Webhook 的時間戳記是秒還是毫秒?
Meta 的訊息範例中,timestamp 與 entry 的時間都以毫秒表示。若當作秒讀取,會變成遙遠未來的日期。
如何從 Instagram 私訊 Webhook 取得發送者的用戶名稱?
呼叫 GET /<IGSID>,並指定 name 與 username 等欄位。事件只包含用戶的 Instagram 範圍 ID。
為什麼我的 Instagram 私訊 Webhook 沒有抵達?
請檢查:帳戶是否已開啟「允許存取訊息」;是否已透過 /subscribed_apps 訂閱 messages;應用程式是否處於 Live 模式,且對非其擁有的帳戶具備 Advanced Access。
easyCoexistence 會轉發 Instagram 訊息的表情回應嗎?
不會。表情回應位於 message_reactions 中,而 easyCoexistence 只為帳戶訂閱 messages、comments 與 mentions。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期