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 端点,过程中不保留任何副本,因此您的智能体或代码可在需要时获取所需媒体。
分享帖子的附件类型;其负载在 url 之外还包含 ig_post_media_id 与 title,即帖子的文案。
旧版 share 附件类型不再支持 Instagram 帖子分享的日期。
限时消失、单次查看媒体的附件类型,到达时不含 URL。
消息事件上设为 true,表示该消息含有不受支持的媒体。
有人回应或转发轮播帖子中某张图片时,通知所报告的图片。
私信事件可以携带哪些附件类型?
Meta 的 Instagram Login 示例列出了 message.attachments[].type 的以下取值,每个附带一个 payload 对象。大多数负载包含指向 Meta CDN 上媒体的 url,Meta 仅为 ig_post 记录了额外的负载字段,因此应先读取 type,再读取负载。
带附件的私信是什么样子?
一个 messages 事件,其消息对象含有 attachments 而非文本,或与文本并存。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 将它们与内容绑定。其概述称 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。
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 监控
验证时间