Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

story_mention

Tipo de anexo do evento messages que a Meta envia quando alguém menciona a conta no seu Story.

link_sticker_url

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.

24 hours

Duração de um Story; depois de expirar ou ser eliminado, o URL da menção deixa de ser apresentado.

Public

Contas cujas menções em Stories chegam; a menção de uma conta privada só chega se seguir a conta profissional.

GIF, sticker

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:

A Story mention, as Meta sends it
{
  "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.

The message object of a Story reply
"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_mention e payload.url: uma menção, e o URL da CDN do Story que a originou.
  • reply_to.story.url e reply_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.

A forwarded Story mention, headers included
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.
Fazer isto com a EasyCoexistence

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