Instagram DM attachments in the messages webhook
Instagram's messages webhook carries DM media in message.attachments: an array of objects, each with a type and a payload that usually holds a CDN url. Meta's list for Instagram Login names image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story and the legacy share, and view-once media arrives as an ephemeral attachment with no URL.
easyCoexistence subscribes each connected Instagram account to messages and forwards DMs with their attachments to your HTTPS endpoint as Meta sends them, signed with that account's secret and with no copy kept, so your agent or code fetches the media it needs.
Attachment type for a shared post; its payload adds ig_post_media_id and title, the post's caption, next to url.
When the old share attachment type stopped being supported for Instagram post shares.
Attachment type of disappearing, view-once media, which arrives with no URL.
Set to true on a message event when the message contains unsupported media.
What a notification reports when someone reacts to or forwards one image of a carousel post.
Which attachment types can a DM event carry?
Meta's Instagram Login examples list these values for message.attachments[].type, each with a payload object. Most payloads hold a url to the media on Meta's CDN, and Meta documents extra payload fields for ig_post only, so read the type before the payload.
What does a DM with attachments look like?
A messages event whose message object holds attachments instead of text, or next to it. Meta's sample sends two media items in one message, each with its own type and payload.url, so a handler has to loop over the array rather than read its first element:
{
"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>" } }
]
}
}
]
}
]
}What does a shared post look like?
An ig_post attachment. From 3 November 2025 Meta sent post shares with both a share and an ig_post attachment; share was supported for posts until 1 February 2026, and Meta says new integrations must support ig_post. Its payload adds the post's media ID and its caption as title:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]What does each field mean?
The attachment fields Meta documents for a DM event, from the array down:
- message.attachments[]: one object per media item; Meta's sample carries two in one message.
- type: what the item is, from the list above. Branch on it before reading the payload.
- payload.url: a CDN URL for the media. Meta's overview calls these URLs privacy-aware: they return nothing once the content is deleted or has expired.
- payload.
ig_post_media_idand payload.title: onig_postonly, the shared post's media ID and its caption. - message.text: present only when the message also contains text.
- message.
is_unsupported: true when the message contains media the webhook does not support.
How long do attachment URLs work?
Meta ties them to the content. Its overview says Instagram's CDN URLs are privacy-aware and stop returning media once the content has been deleted or has expired, and its story mention guide says a Story's URL stops rendering when the Story expires or is deleted. An app that needs a file should fetch it when the event arrives, within Meta's rules: Story media, for one, must not be stored or cached.
Which media does the webhook leave out?
Meta's Instagram Messaging guide names these gaps, which a handler should expect rather than treat as errors:
- Disappearing media, view once or allow replay: an attachment of type ephemeral, with no URL.
- Unsupported media: the message arrives with
is_unsupportedset to true. - GIFs and stickers: that guide says they trigger no webhook, while Meta's Instagram Login examples list them under image.
- The chosen carousel image: a reaction to, or forward of, one image in a carousel post reports the first image.
- Shares in general: Meta's messaging guides still say only the URL of shared media is included, though
ig_postnow adds the media ID and caption.
How does easyCoexistence forward attachments?
Unchanged, inside the entry: a DM with media reaches your endpoint with Meta's attachments array as Meta sent it, in an envelope of platform, account_id, external_id and entry, signed with X-EC-Signature. Attachments are not downloaded, and events are not stored by default: an account with an automation switched on keeps a DM's text, not its media, for 7 days. Fetch the media you need from payload.url when the event arrives, and leave Story media unstored.
Common mistakes
- Reading only the first attachment. message.attachments is an array, and Meta's sample carries two items in one message, so loop over it.
- Still matching type share for shared posts. Meta supported it for posts until 1 February 2026; read ig_post, with the media ID and caption in its payload.
- Saving payload.url to fetch later. It stops returning media once the content is deleted or expires, so download what you need on arrival, Story media excepted.
- Reading payload.url without checking the type. View-once media arrives as ephemeral with no URL, and unsupported media sets is_unsupported instead.
send_social_dm replies inside the 24-hour window. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Can I store media from an Instagram DM attachment?
Download what you need when the event arrives, since payload.url stops returning media once the content is deleted or expires. Story media is the exception: Meta's rules say it must not be stored or cached.
Why does an Instagram DM webhook have no media URL?
Usually because the media is view-once, which arrives as an ephemeral attachment with no URL, or unsupported, which sets is_unsupported to true.
Do Instagram GIFs and stickers trigger the messages webhook?
Meta's docs disagree: its Instagram Login examples list GIFs and stickers under image, while its Instagram Messaging guide says they trigger no webhook. Test with a real account.
Can one Instagram DM event carry several attachments?
Yes. message.attachments is an array, and Meta's sample shows two media items in a single message.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on