messages Webhook 中的 Instagram 私訊附件
Instagram 的 messages Webhook 會把私訊媒體放在 message.attachments 中:這是一個陣列,每個物件都有 type 和負載,負載通常包含 CDN 的 url。Meta 為 Instagram Login 列出的類型有 image、video、audio、file、ig_post、ig_reel、reel、story_mention、media、story、ig_story,以及舊版的 share;閱後即焚的媒體則以不含 URL 的 ephemeral 附件送達。
easyCoexistence 為每個已連接的 Instagram 帳戶訂閱 messages,將帶附件的私訊依 Meta 原樣連同附件轉發至你的 HTTPS 端點,並以該帳戶的密鑰簽署,不保留副本,讓你的 AI 代理或程式自行取得所需媒體。
分享貼文的附件類型,負載除 url 外還有 ig_post_media_id 和 title(即貼文的說明文字)。
舊版 share 附件類型停止支援 Instagram 貼文分享的日期。
閱後即焚、只能觀看一次的媒體所用的附件類型,送達時沒有 URL。
訊息事件中,若訊息含有不受支援的媒體,則 is_unsupported 設為 true。
有人對多圖貼文中的一張圖片作出反應或轉發時,通知所報告的內容。
哪些附件類型可以出現在私訊事件中?
Meta 為 Instagram Login 提供的示例列出了 message.attachments[].type 的以下值,每個值都附有一個負載物件。大多數負載包含指向 Meta CDN 上媒體的 url,而 Meta 只為 ig_post 記錄額外的負載欄位,因此應先判斷類型,再讀取負載。
帶附件的私訊事件是什麼樣子?
一個 messages 事件,其 message 物件包含附件而非文字,或在文字之外另含附件。Meta 的示例在同一則訊息中傳送兩件媒體,每件都有各自的 type 和 payload.url,因此處理程式必須逐一走訪陣列,而不是只讀取第一個元素:
{
"object": "instagram",
"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": "<CDN_URL>" } },
{ "type": "video", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
]
}分享貼文是什麼樣子?
是一個 ig_post 附件。自 2025 年 11 月 3 日起,Meta 傳送貼文分享時會同時附上 share 和 ig_post 附件;share 對貼文的支援持續到 2026 年 2 月 1 日,Meta 表示新整合必須支援 ig_post。其負載會加入貼文的媒體 ID,以及作為 title 的說明文字:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]各個欄位的意思是什麼?
Meta 為私訊事件記錄的附件欄位,由陣列往下逐層說明:
- message.attachments[]:每個媒體項目對應一個物件;Meta 的示例在一則訊息中帶有兩個。
- type:項目的種類,見上方列表。讀取負載前,先依此判斷。
- payload.url:媒體的 CDN URL。Meta 的概覽稱這些 URL 具私隱保護設計:內容被刪除或過期後,便不再回傳任何東西。
- payload.
ig_post_media_id和 payload.title:僅適用於ig_post,分別為所分享貼文的媒體 ID 和其說明文字。 - message.text:僅在訊息同時含有文字時出現。
- message.
is_unsupported:訊息含有 Webhook 不支援的媒體時為 true。
附件 URL 能使用多久?
Meta 將 URL 與內容綁定。其概覽指 Instagram 的 CDN URL 具私隱保護設計,內容被刪除或過期後便不再回傳媒體;其限時動態提及指南則表示,限時動態的 URL 在限時動態過期或被刪除後即停止顯示。應用程式如需檔案,應在事件送達時取得,並遵守 Meta 的規則:例如限時動態媒體不得儲存或快取。
Webhook 會遺漏哪些媒體?
Meta 的 Instagram 訊息指南列出了以下缺口,處理程式應預期其存在,而非當作錯誤:
- 閱後即焚媒體、一次觀看或允許重播的媒體:附件類型為 ephemeral,且沒有 URL。
- 不受支援的媒體:訊息會以
is_unsupported設為 true 送達。 - GIF 和貼圖:該指南表示它們不會觸發 Webhook,而 Meta 的 Instagram Login 示例則將它們列於 image 之下。
- 多圖貼文中的所選圖片:對貼文中某張圖片作出反應或轉發時,通知報告的是第一張圖片。
- 一般分享:Meta 的訊息指南仍寫明分享媒體只包含 URL,不過
ig_post現已加入媒體 ID 和說明文字。
easyCoexistence 如何轉發附件?
在 entry 內維持不變:附有媒體的私訊會以 Meta 傳送的 attachments 陣列原樣送達您的端點,外層封包含 platform、account_id、external_id 及 entry,並以 X-EC-Signature 簽署。附件不會下載,預設亦不儲存事件:開啟自動化的帳戶會將私訊的文字(而非媒體)保留 7 天。須在事件送達時從 payload.url 取得所需媒體,並且不要儲存限時動態媒體。
常見錯誤
- 只讀取第一個附件。message.attachments 是陣列,而 Meta 的示例在一則訊息中帶有兩個項目,因此應逐一走訪。
- 仍以 type share 比對分享貼文。Meta 對貼文的支援持續到 2026 年 2 月 1 日;請讀取 ig_post,媒體 ID 和說明文字位於其負載中。
- 儲存 payload.url 以便稍後取得。內容被刪除或過期後,該 URL 便不再回傳媒體,因此應在送達時下載所需內容,限時動態媒體除外。
- 不檢查類型便讀取 payload.url。閱後即焚媒體以 ephemeral 送達,且沒有 URL;不受支援的媒體則會設置 is_unsupported。
send_social_dm 可於 24 小時的回覆時限內回覆。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。
常見問題
我可以儲存 Instagram 私訊附件中的媒體嗎?
請在事件送達時下載所需內容,因為內容被刪除或過期後,payload.url 便不再回傳媒體。限時動態媒體是例外:Meta 的規則規定不得儲存或快取。
為什麼 Instagram 私訊 Webhook 沒有媒體 URL?
通常是因為媒體屬閱後即焚,會以不含 URL 的 ephemeral 附件送達;或媒體不受支援,此時 is_unsupported 會設為 true。
Instagram 的 GIF 和貼圖會觸發 messages Webhook 嗎?
Meta 的文件前後不一致:其 Instagram Login 示例將 GIF 和貼圖列於 image 之下,而其 Instagram 訊息指南則表示它們不會觸發 Webhook。請以真實帳戶測試。
一個 Instagram 私訊事件能否帶有多個附件?
可以。message.attachments 是陣列,而 Meta 的示例在單一則訊息中展示了兩個媒體項目。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期