Instagram messages webhook: the DM payload, echoes and fields
Instagram's messages webhook field delivers a professional account's DMs as they arrive: text, attachments, shares, Story replies and mentions, inline replies and deletions. Each event sits in a messaging array with the sender's Instagram-scoped ID, the recipient, a timestamp and a message object, and messages the account itself sends come back on the same field with is_echo set to true.
easyCoexistence subscribes each connected Instagram account to messages and forwards its DMs, echoes included, to your HTTPS endpoint as they arrive, signed with that account's secret; forwarding keeps no copy, and DMs are not stored by default.
Set to true on a message event for a message the account itself sent.
Standard messaging window for most user actions, during which the app can reply to the person.
Attachment type for a shared post; the old share type was supported only until February 1, 2026.
Attachment type of the DM event Meta sends when someone mentions the account in their Story.
Error subcode, under code 200, when the account owner has disabled access to Instagram direct messages.
When does the messages field fire?
When a person sends the professional account a DM, and when the account sends one. Meta's examples and references list these cases, each a messaging event with a message object:
- Text, and media as attachments: images, video, audio and files.
- A shared post or Reel, as an
ig_post,ig_reelor reel attachment. - A reply to the account's Story, with
reply_to.story, and a Story that mentions the account, as astory_mentionattachment. - An inline reply to an earlier message, with
reply_to.mid, and a quick reply, withquick_reply.payload. - A message the person deleted (
is_deleted), unsupported media (is_unsupported), and a message from someone who clicked a Click-to-Direct ad (referral). - A message the account sent, which comes back with
is_echoset to true.
What does a messages notification look like?
A POST whose JSON has object set to instagram. Unlike a comment, a message sits in a messaging array inside the account's entry, and each element carries sender, recipient, timestamp and message. A reply to the account's Story looks like this:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}What does each field mean?
The fields Meta documents for a message event under Instagram Login, from the outside in:
- entry[].id: the professional account's ID. entry[].time: when Meta sent the notification; Meta's messaging samples give it in milliseconds.
- sender.id and recipient.id: on an incoming DM, the person's Instagram-scoped ID and the account's ID; on an echo, the same two the other way round.
- timestamp: when the message was sent, in milliseconds in Meta's samples. Order messages by it, not by arrival.
- message.mid: the message ID, for deduplicating, reacting, and replying to that message with
reply_to.mid. - message.text: included when the message contains text.
- message.attachments[]: each with a type and a payload, usually a url. A shared post's
ig_postpayload addsig_post_media_idand title, its caption. - message.
reply_to: mid for an inline reply, or story with the Story's url and id for a Story reply. - message.
quick_reply.payload and message.referral: the quick reply chosen, and the Click-to-Direct ad's ref,ad_id, source, type andads_context_data. - message.
is_deleted,is_echo,is_selfandis_unsupported: included only when true. - message.
admin_textandhandoff_reason: on eligible apps, a notice that a Meta application, such as Meta Business Agent, handed the conversation off; it can arrive with no mid or text.
How do echoes work?
When the account sends a message, Meta sends a messages event for it as well, with is_echo set to true. sender.id is then the account and recipient.id the person's Instagram-scoped ID, and a test message the account sends to itself also carries is_self. Echoes record what the account said, which a conversation log needs, but a handler deciding whether to reply has to skip them. Meta sends no echo when the account reacts to a message or removes a reaction.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}Which ID do you reply to?
sender.id, the person's Instagram-scoped ID. Meta creates it when someone messages the account or comments on its media, and it is specific to that person and that account. POST /<IG_ID>/messages with recipient.id set to it sends the reply. The event carries no name or username; GET /<IGSID> with fields such as name and username returns them, because a person who has messaged the account has given the consent that lookup needs.
How does a message open the 24-hour window?
An app can message a person only after they have messaged the account, and only within the standard messaging window their action opens. For most actions it lasts 24 hours, and up to 7 days from a first message sent after clicking a Click-to-Direct ad. A new message from the person opens a new window, so their latest timestamp is the one to track; an echo is the account's own message and extends nothing. Replies written by a person can use Meta's separate 7-day Human Agent window, tagged human_agent.
What does a messages event not carry?
A few things a handler might look for are missing, according to Meta's messaging references:
- The person's name or username: only the Instagram-scoped ID, which GET /<IGSID> resolves.
- View-once media: it arrives as an ephemeral attachment with no URL.
- The exact carousel image: a reaction to, or a forward of, one image in a carousel post reports the first image.
- Reactions, edits and read receipts, which come on fields of their own.
- A read mark: a message delivered by webhook stays unread in the Instagram inbox until a reply is sent.
Which other messaging fields does Meta list?
Meta's field list and examples for Instagram Login name these besides messages, each a messaging event of its own. easyCoexistence subscribes each account to messages, comments and mentions only, so none of them is part of what it forwards:
message_reactions: a person reacts to a message or removes the reaction, with reaction.mid, action set to react or unreact, and the reaction and emoji.message_edit: a person edits a message, withmessage_edit.mid, the new text andnum_edit.messaging_postbacks: a person taps an icebreaker or a template button, with postback.mid, title and payload.messaging_referral: a person already in a conversation opens an ig.me link with a ref parameter.messaging_seen: a person reads a message, with read.mid.messaging_optins,messaging_handoverand standby: the last two for apps sharing a conversation under Meta's handover protocol.
What must the account turn on?
Allow access to messages. Meta requires a professional account to turn it on before its messages can be managed through the API, in the Instagram app under Settings, Messages and story replies, Message controls, Connected tools. While it is off, sends fail with code 200, subcode 2534041. The app also needs instagram_business_basic and instagram_business_manage_messages, with Advanced Access to serve accounts it does not own or manage.
How does easyCoexistence forward a DM?
Like a comment: each entry Meta delivers for the account is POSTed to your HTTPS endpoint inside an envelope of platform, account_id, external_id and entry, signed in X-EC-Signature with the account's secret, once and with no copy kept. Echoes are forwarded with the rest, so check is_echo before replying. To answer, call send_social_dm with the account_id and the event's sender.id as recipient_id, inside the 24-hour window. Automations that start on a DM run on the same events.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"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": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}Common mistakes
- Replying to echoes. An event with is_echo set is the account's own message, and a reply to it sends the account into a loop with itself.
- Assuming a message always has text. Attachments, shares, Story mentions and deletions arrive without a text field, so branch on what the message object holds.
- Ordering messages by arrival. Meta can deliver messages out of order after a failure, so sort them by timestamp.
- Parsing time and timestamp as seconds. Meta's messaging samples give both in milliseconds, and read as seconds they become dates far in the future.
send_social_dm replies inside the 24-hour window, and automations can reply on their own with a fixed text or AI. 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
Are Instagram message webhook timestamps in seconds or milliseconds?
Milliseconds, in Meta's messaging samples, for both timestamp and entry time. Read as seconds, they turn into dates far in the future.
How do I get the sender's username from an Instagram DM webhook?
Call GET /<IGSID> with fields such as name and username. The event carries only the person's Instagram-scoped ID.
Why are my Instagram DM webhooks not arriving?
Check that the account turned on Allow access to messages, that it is subscribed to messages through /subscribed_apps, and that the app is Live with Advanced Access for accounts it does not own.
Does easyCoexistence forward Instagram message reactions?
No. Reactions come on message_reactions, and easyCoexistence subscribes accounts to messages, comments and mentions.
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