登录开始免费试用
easyCoexistence 官方 API

messages Webhook 中的 Instagram 私信附件

Instagram 的 messages Webhook 在 message.attachments 中携带私信媒体:这是一个对象数组,每个对象含有 type,以及通常保存 CDN 上 url 的 payload。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 端点,过程中不保留任何副本,因此您的智能体或代码可在需要时获取所需媒体。

ig_post

分享帖子的附件类型;其负载在 url 之外还包含 ig_post_media_id 与 title,即帖子的文案。

1 Feb 2026

旧版 share 附件类型不再支持 Instagram 帖子分享的日期。

ephemeral

限时消失、单次查看媒体的附件类型,到达时不含 URL。

is_unsupported

消息事件上设为 true,表示该消息含有不受支持的媒体。

First image

有人回应或转发轮播帖子中某张图片时,通知所报告的图片。

私信事件可以携带哪些附件类型?

Meta 的 Instagram Login 示例列出了 message.attachments[].type 的以下取值,每个附带一个 payload 对象。大多数负载包含指向 Meta CDN 上媒体的 url,Meta 仅为 ig_post 记录了额外的负载字段,因此应先读取 type,再读取负载。

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 事件,其消息对象含有 attachments 而非文本,或与文本并存。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 将它们与内容绑定。其概述称 Instagram 的 CDN URL 具备隐私保护特性,内容被删除或过期后便不再返回媒体;其 Story 提及指南也称,Story 过期或被删除后,其 URL 将停止渲染。需要某个文件的应用应在事件到达时获取,并遵守 Meta 的规则:例如 Story 媒体不得存储或缓存。

Webhook 会遗漏哪些媒体?

Meta 的 Instagram 消息指南列出以下缺口,处理程序应预期到这些情况,而不是将其视为错误:

  • 限时消失、单次查看或允许重播的媒体:类型为 ephemeral 的附件,不含 URL。
  • 不受支持的媒体:消息到达时 is_unsupported 设为 true。
  • GIF 与贴纸:该指南称它们不会触发 Webhook,而 Meta 的 Instagram Login 示例却将其列在 image 之下。
  • 所选轮播图片:对轮播帖子中某张图片的回应或转发,报告的是第一张图片。
  • 一般分享:Meta 的消息指南仍称,只包含分享媒体的 URL,不过 ig_post 现在新增了媒体 ID 与文案。

easyCoexistence 如何转发附件?

条目内保持不变:带媒体的私信会携带 Meta 原样发送的 attachments 数组到达您的端点,外层信封包含 platform、account_id、external_id 和 entry,并使用 X-EC-Signature 签名。附件不会被下载,事件默认不予存储:开启自动化的账户会将私信文本(而非媒体)保留 7 天。请在事件到达时从 payload.url 获取所需媒体,并且不要存储 Story 媒体。

常见错误

  • 只读取第一个附件。message.attachments 是一个数组,而 Meta 的示例在一条消息中携带两项,因此应遍历它。
  • 分享帖子仍在匹配 share 类型。Meta 对帖子的支持持续到 2026 年 2 月 1 日;应读取 ig_post,其负载中含媒体 ID 与文案。
  • 保存 payload.url 以便稍后获取。内容被删除或过期后它便不再返回媒体,因此应在到达时下载所需内容,Story 媒体除外。
  • 未检查类型就读取 payload.url。单次查看的媒体以不含 URL 的 ephemeral 形式到达,而不受支持的媒体则会设置 is_unsupported。
使用 EasyCoexistence 完成这些操作

send_social_dm 在 24 小时窗口内回复。每个连接每月 US$ 9 起,连接越多价格越低,最低降至 US$ 0.75,首 3 天免费试用。

常见问题

能否存储 Instagram 私信附件中的媒体?

在事件到达时下载所需内容,因为 payload.url 在内容被删除或过期后便不再返回媒体。Story 媒体是例外: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 监控

验证时间