Menções e respostas a Stories do Instagram no webhook
O Instagram entrega menções e respostas a Stories como mensagens diretas no campo messages do webhook. Uma menção chega como uma mensagem cujo campo attachments contém um item do tipo story_mention, com o URL da CDN do Story em payload.url. Uma resposta traz o texto da pessoa e reply_to.story com o url e o id do Story e, num Story com autocolante de ligação, link_sticker_url.
O easyCoexistence subscreve cada conta do Instagram ligada a messages, por isso as menções e respostas em Stories chegam ao seu endpoint HTTPS, juntamente com as restantes mensagens diretas, à medida que acontecem, assinadas com o segredo dessa conta e sem cópia guardada.
Tipo de anexo do evento messages que a Meta envia quando alguém menciona a conta no seu Story.
Campo que a Meta acrescentou a reply_to.story a 12 de dezembro de 2025, com o URL do autocolante de ligação do Story respondido.
Duração de um Story; depois de expirar ou ser eliminado, o URL da menção deixa de ser apresentado.
Contas cujas menções em Stories chegam; a menção de uma conta privada só chega se seguir a conta profissional.
Respostas a Stories que o webhook não suporta, segundo o guia de mensagens do Instagram da Meta.
Como chega uma menção num Story?
Como mensagem direta. Quando alguém menciona a conta profissional no seu Story, o Instagram coloca na caixa de entrada da conta uma mensagem que referencia esse Story, e a Meta envia para ela um evento messages. sender.id é o ID com âmbito Instagram da pessoa, e message.attachments contém um item do tipo story_mention cujo payload.url é o URL da CDN do Story. Os exemplos da Meta não têm texto, por isso leia o anexo:
{
"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>" }
}
]
}
}
]
}
]
}Como chega uma resposta a um Story?
Também como mensagem direta, com a mensagem da pessoa e um objeto reply_to que aponta para o Story da conta. reply_to.story transporta o URL da CDN do Story e o seu id. A referência de webhooks da Meta indica também link_sticker_url nesse campo, acrescentado em dezembro de 2025 para respostas a Stories com autocolante de ligação, que a Meta sugere para encaminhar automatizações por ligação. Uma resposta em linha a uma mensagem anterior usa, em vez disso, reply_to.mid.
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}O que significa cada campo?
Os campos que a Meta documenta para estes dois eventos, de fora para dentro:
- entry[].id e recipient.id: a conta profissional. sender.id: o ID com âmbito Instagram da pessoa, o ID para o qual vai uma resposta.
- timestamp: quando a mensagem foi enviada, em milissegundos nos exemplos da Meta; entry[].time é quando a Meta enviou a notificação.
- message.mid: o ID da mensagem, para deduplicar as novas tentativas e para responder com
reply_to.mid. - attachments[].type
story_mentione payload.url: uma menção, e o URL da CDN do Story que a originou. reply_to.story.url ereply_to.story.id: o Story da conta a que a pessoa respondeu.reply_to.story.link_sticker_url: o URL do autocolante de ligação desse Story.- message.text: as palavras da resposta, incluídas quando a mensagem tem texto.
Quanto tempo funciona o URL do Story?
Enquanto o Story existir. Um Story desaparece ao fim de 24 horas ou quando o autor o elimina, e o guia de menções em Stories da Meta diz que o URL deixa então de ser apresentado; a visão geral acrescenta que os URLs da CDN do Instagram respeitam a privacidade e não devolvem nada para conteúdo eliminado ou expirado. O mesmo guia permite manter o URL da CDN mas não o conteúdo: uma aplicação não deve armazenar nem colocar em cache o conteúdo do Story nos seus servidores, e deve mostrar um marcador de posição quando o Story já não existir.
Quando nenhum dos dois eventos é disparado?
Os guias da Meta indicam estes casos, em que um manipulador à espera de um evento de Story não recebe nada:
- Uma menção num Story feita por uma conta privada que não segue a conta profissional.
- Uma marcação numa publicação normal: a Meta diz que só as menções em Stories disparam o webhook de mensagens, e não as marcações em publicações.
- Uma resposta a um Story feita com um GIF ou um autocolante, que o webhook não suporta.
- Stories através da API de menções: GET /<
IG_ID>/tags e POST /<IG_ID>/mentions não os suportam, por isso a mensagem direta é a forma como chega uma menção num Story.
As menções e respostas em Stories abrem a janela de mensagens?
Uma resposta é uma mensagem da pessoa, e a Meta inclui as menções em Stories entre os canais através dos quais uma pessoa inicia uma conversa. A janela aberta pela ação dura 24 horas para a maioria das ações, por isso a conta pode responder com POST /<IG_ID>/messages e recipient.id igual ao sender.id do evento enquanto a janela estiver aberta. A resposta da conta volta em messages como eco, com is_echo a true.
Como o easyCoexistence os encaminha?
No campo messages, ao qual cada conta ligada está subscrita, por isso as menções e as respostas em Stories chegam ao seu endpoint com as restantes mensagens diretas da conta: cada entrada dentro de um envelope com platform, account_id, external_id e entry, assinada em X-EC-Signature com o segredo da conta, enviada uma só vez e sem cópia guardada. send_social_dm responde à pessoa com o sender.id do evento como recipient_id, dentro da janela de 24 horas.
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>" } }
]
}
}
]
}
}Erros comuns
- Guardar o conteúdo do Story. O guia de menções em Stories da Meta permite manter o URL da CDN, não o conteúdo, que não deve ser armazenado nem colocado em cache nos seus servidores.
- Ler apenas message.text. Uma menção num Story traz um anexo do tipo story_mention e, nos exemplos da Meta, nenhum texto, por isso um manipulador só de texto vê uma mensagem vazia.
- Apresentar o URL do Story dias depois. Deixa de funcionar quando o Story expira ao fim de 24 horas ou é eliminado, por isso a partir daí mostre um marcador de posição.
- Procurar menções em Stories no campo comments ou na API de menções. A Meta entrega-as como mensagens diretas em messages.
send_social_dm responde à pessoa dentro da janela de 24 horas, com o Claude, o ChatGPT ou o seu próprio código. De US$ 9 a US$ 0,75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
O evento de menção num Story do Instagram inclui texto?
Não nos exemplos da Meta. Uma menção num Story traz um anexo do tipo story_mention com o URL da CDN do Story, por isso um manipulador que lê apenas message.text vê uma mensagem vazia.
O que é link_sticker_url numa resposta a um Story do Instagram?
É o URL do autocolante de ligação do Story a que a pessoa respondeu, em reply_to.story.link_sticker_url. A Meta acrescentou-o a 12 de dezembro de 2025 e sugere-o para encaminhar automatizações por ligação.
Respostas a um Story com GIF ou autocolante disparam o webhook?
Não. O guia de mensagens do Instagram da Meta diz que o webhook não suporta respostas a Stories feitas com um GIF ou um autocolante.
Contas privadas disparam webhooks de menções em Stories?
Só quando a conta privada segue a conta profissional. As menções de contas públicas chegam à medida que acontecem.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em