Instagram story mentions and story replies in the webhook
Instagram delivers Story mentions and Story replies as DMs on the messages webhook field. A mention arrives as a message whose attachments hold an item of type story_mention, with the Story's CDN URL in payload.url. A reply carries the person's text and reply_to.story with the Story's url and id and, for a Story with a link sticker, link_sticker_url.
easyCoexistence subscribes each Instagram account to messages, relays Story mentions and replies to your HTTPS endpoint, signed per account and not stored by default, and send_social_dm replies inside the 24-hour window.
Attachment type of the messages event Meta sends when someone mentions the account in their Story.
Field Meta added to reply_to.story on 12 December 2025, holding the link sticker URL of the Story answered.
How long a Story lasts; once it expires or is deleted, its mention URL stops rendering.
Accounts whose Story mentions arrive; a private account's mention arrives only if it follows the professional account.
Story replies the webhook does not support, according to Meta's Instagram Messaging guide.
How does a Story mention arrive?
As a DM. When a person mentions the professional account in their Story, Instagram puts a message referencing that Story in the account's inbox, and Meta sends a messages event for it. sender.id is the person's Instagram-scoped ID, and message.attachments holds one item of type story_mention whose payload.url is the Story's CDN URL. Meta's samples show no text, so read the attachment:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{
"type": "story_mention",
"payload": { "url": "<CDN_URL>" }
}
]
}
}
]
}
]
}How does a Story reply arrive?
Also as a DM, with the person's message and a reply_to object pointing at the account's Story. reply_to.story carries the Story's CDN url and its id. Meta's webhook reference also lists link_sticker_url there, added in December 2025 for replies to Stories with a link sticker, which Meta suggests for routing automations by link. An inline reply to an earlier message uses reply_to.mid instead.
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}What does each field mean?
The fields Meta documents for these two events, from the outside in:
- entry[].id and recipient.id: the professional account. sender.id: the person's Instagram-scoped ID, the ID a reply goes to.
- timestamp: when the message was sent, in milliseconds in Meta's samples; entry[].time is when Meta sent the notification.
- message.mid: the message ID, for deduplicating retries and for replying with
reply_to.mid. - attachments[].type
story_mentionand payload.url: a mention, and the CDN URL of the Story that made it. reply_to.story.url andreply_to.story.id: the account's Story the person answered.reply_to.story.link_sticker_url: the URL on that Story's link sticker.- message.text: the reply's words, included when the message contains text.
How long does the Story URL work?
As long as the Story does. A Story disappears after 24 hours or when its author deletes it, and Meta's story mention guide says the URL then stops rendering; its overview adds that Instagram's CDN URLs are privacy-aware and return nothing for deleted or expired content. The same guide allows keeping the CDN URL but not the media: an app must not store or cache the Story's content on its servers, and should show a placeholder once the Story is gone.
When does neither event fire?
Meta's guides name these cases, where a handler waiting for a Story event gets nothing:
- A Story mention by a private account that does not follow the professional account.
- A tag on a regular post: Meta says only Story mentions trigger the messages webhook, not tagging on posts.
- A Story reply made with a GIF or a sticker, which the webhook does not support.
- Stories through the mentions API: GET /<
IG_ID>/tags and POST /<IG_ID>/mentions do not support them, so the DM is how a Story mention arrives.
Do Story mentions and replies open the messaging window?
A reply is a message from the person, and Meta lists Story mentions among the channels through which a person starts a conversation. The window their action opens lasts 24 hours for most actions, so the account can reply with POST /<IG_ID>/messages and recipient.id set to the event's sender.id while it is open. The account's reply comes back on messages as an echo, with is_echo set to true.
How does easyCoexistence forward them?
On the messages field, which each connected account is subscribed to, so Story mentions and Story replies reach your endpoint with the account's other DMs: each entry inside an envelope of platform, account_id, external_id and entry, signed in X-EC-Signature with the account's secret, sent once and with no copy kept. send_social_dm answers the person with the event's sender.id as recipient_id, inside the 24-hour window.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"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": "story_mention", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
}Common mistakes
- Storing the Story's media. Meta's story mention guide allows keeping the CDN URL, not the content, which must not be stored or cached on your servers.
- Reading only message.text. A Story mention carries an attachment of type story_mention and, in Meta's samples, no text, so a text-only handler sees an empty message.
- Rendering the Story URL days later. It stops working once the Story expires after 24 hours or is deleted, so show a placeholder from then on.
- Looking for Story mentions on the comments field or the mentions API. Meta delivers them as DMs on messages.
easyCoexistence subscribes each connected Instagram account to messages, so Story mentions and Story replies reach your HTTPS endpoint with its other DMs as they arrive, signed with that account's secret and with no copy kept. send_social_dm answers the person inside the 24-hour window, from Claude, ChatGPT or your own code. 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
Does an Instagram Story mention event include text?
Not in Meta's samples. A Story mention carries an attachment of type story_mention with the Story's CDN URL, so a handler that reads only message.text sees an empty message.
What is link_sticker_url in an Instagram Story reply?
The URL on the link sticker of the Story the person answered, in reply_to.story.link_sticker_url. Meta added it on 12 December 2025 and suggests it for routing automations by link.
Do GIF or sticker replies to a Story trigger the webhook?
No. Meta's Instagram Messaging guide says the webhook does not support Story replies made with a GIF or a sticker.
Do private accounts trigger Story mention webhooks?
Only when the private account follows the professional account. Mentions from public accounts arrive as they happen.
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