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

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 代理或程式自行取得所需媒體。

ig_post

分享貼文的附件類型,負載除 url 外還有 ig_post_media_id 和 title(即貼文的說明文字)。

1 Feb 2026

舊版 share 附件類型停止支援 Instagram 貼文分享的日期。

ephemeral

閱後即焚、只能觀看一次的媒體所用的附件類型,送達時沒有 URL。

is_unsupported

訊息事件中,若訊息含有不受支援的媒體,則 is_unsupported 設為 true。

First image

有人對多圖貼文中的一張圖片作出反應或轉發時,通知所報告的內容。

哪些附件類型可以出現在私訊事件中?

Meta 為 Instagram Login 提供的示例列出了 message.attachments[].type 的以下值,每個值都附有一個負載物件。大多數負載包含指向 Meta CDN 上媒體的 url,而 Meta 只為 ig_post 記錄額外的負載欄位,因此應先判斷類型,再讀取負載。

imageA photo. Meta's Instagram Login list also puts GIFs and stickers under this type.
videoA video, at payload.url.
audioAudio, at payload.url.
fileA file, at payload.url.
ig_postA shared post: url, ig_post_media_id and title, its caption.
ig_reel and reelA shared Reel; Meta lists both names, each with a url.
story_mentionA Story that mentions the account, at its CDN URL.
shareThe legacy post share, supported until 1 February 2026.
media, story, ig_storyAlso in Meta's list, with no payload described.
ephemeralView-once media, sent with no URL.

帶附件的私訊事件是什麼樣子?

一個 messages 事件,其 message 物件包含附件而非文字,或在文字之外另含附件。Meta 的示例在同一則訊息中傳送兩件媒體,每件都有各自的 type 和 payload.url,因此處理程式必須逐一走訪陣列,而不是只讀取第一個元素:

A DM with two attachments, as Meta sends it
{
  "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 的說明文字:

The attachment of a shared post
"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。
使用 EasyCoexistence 完成這項設定

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 監察

驗證日期