EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Menções e respostas a Story no Instagram no webhook

O Instagram entrega menções e respostas a Story como DMs no campo messages do webhook. Uma menção chega como mensagem cujos attachments trazem um item do tipo story_mention, com a URL do CDN do Story em payload.url. Uma resposta traz o texto da pessoa e reply_to.story com a url e o id do Story e, para um Story com figurinha de link, link_sticker_url.

O easyCoexistence inscreve cada conta do Instagram em messages, repassa menções e respostas a Story ao seu endpoint HTTPS, assinadas por conta e não armazenadas por padrão, e o send_social_dm responde dentro da janela de 24 horas.

story_mention

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

link_sticker_url

Campo que a Meta adicionou a reply_to.story em 12 de dezembro de 2025, com a URL da figurinha de link do Story respondido.

24 hours

Por quanto tempo um Story dura; depois que expira ou é apagado, a URL da menção deixa de renderizar.

Public

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

GIF, sticker

Respostas a Story que o webhook não suporta, segundo o guia de Mensagens do Instagram da Meta.

Como chega uma menção a Story?

Como DM. Quando alguém menciona a conta profissional no Story dele, o Instagram coloca na caixa de entrada da conta uma mensagem que referencia esse Story, e a Meta envia um evento de messages para ela. sender.id é o ID do Instagram com escopo da pessoa, e message.attachments traz um item do tipo story_mention cujo payload.url é a URL do CDN do Story. Os exemplos da Meta não trazem texto, então 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 Story?

Também como DM, com a mensagem da pessoa e um objeto reply_to apontando para o Story da conta. reply_to.story traz a url do CDN do Story e o seu id. A referência de webhooks da Meta também lista ali link_sticker_url, adicionado em dezembro de 2025 para respostas a Stories com figurinha de link, que a Meta sugere para rotear automações por link. Uma resposta em linha a uma mensagem anterior usa reply_to.mid no lugar.

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 esses dois eventos, de fora para dentro:

  • entry[].id e recipient.id: a conta profissional. sender.id: o ID do Instagram com escopo da pessoa, o ID para onde 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 repetições e para responder com reply_to.mid.
  • attachments[].type story_mention e payload.url: uma menção e a URL do CDN do Story que a gerou.
  • reply_to.story.url e reply_to.story.id: o Story da conta que a pessoa respondeu.
  • reply_to.story.link_sticker_url: a URL da figurinha de link desse Story.
  • message.text: as palavras da resposta, incluídas quando a mensagem contém texto.

Por quanto tempo a URL do Story funciona?

Enquanto o Story existir. Um Story desaparece após 24 horas ou quando o autor o apaga, e o guia de menções em Story da Meta diz que a URL então deixa de renderizar; a visão geral acrescenta que as URLs do CDN do Instagram respeitam a privacidade e não retornam nada para conteúdo apagado ou expirado. O mesmo guia permite guardar a URL do CDN, mas não a mídia: o app não pode armazenar nem colocar em cache o conteúdo do Story em seus servidores, e deve mostrar um placeholder quando o Story não existir mais.

Quando nenhum dos dois eventos dispara?

Os guias da Meta citam estes casos, em que um handler que espera um evento de Story não recebe nada:

  • Uma menção a Story feita por conta privada que não segue a conta profissional.
  • Uma marcação em publicação comum: a Meta diz que só menções em Story disparam o webhook de messages, não marcações em posts.
  • Uma resposta a Story feita com GIF ou figurinha, que o webhook não suporta.
  • Stories pela API de menções: GET /<IG_ID>/tags e POST /<IG_ID>/mentions não os suportam, então a DM é como chega uma menção a Story.

Menções e respostas a Story abrem a janela de mensagens?

Uma resposta é uma mensagem da pessoa, e a Meta lista as menções a Story entre os canais pelos quais uma pessoa inicia uma conversa. A janela aberta pela ação dura 24 horas para a maioria das ações, então a conta pode responder com POST /<IG_ID>/messages e recipient.id igual ao sender.id do evento enquanto ela estiver aberta. A resposta da conta volta em messages como echo, com is_echo igual a true.

Como o easyCoexistence as encaminha?

No campo messages, ao qual cada conta conectada está inscrita, então menções e respostas a Story chegam ao seu endpoint junto com as demais DMs da conta: cada entrada dentro de um envelope com platform, account_id, external_id e entry, assinado em X-EC-Signature com o segredo da conta, enviado uma vez e sem manter cópia. 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

  • Armazenar a mídia do Story. O guia de menções em Story da Meta permite guardar a URL do CDN, não o conteúdo, que não pode ser armazenado nem colocado em cache nos seus servidores.
  • Ler apenas message.text. Uma menção a Story traz um anexo do tipo story_mention e, nos exemplos da Meta, nenhum texto, então um handler que só lê texto vê uma mensagem vazia.
  • Renderizar a URL do Story dias depois. Ela deixa de funcionar quando o Story expira após 24 horas ou é apagado, então mostre um placeholder a partir daí.
  • Procurar menções a Story no campo comments ou na API de menções. A Meta as entrega como DMs em messages.
Fazendo isso com o EasyCoexistence

O easyCoexistence inscreve cada conta do Instagram conectada em messages, então menções e respostas a Story chegam ao seu endpoint HTTPS junto com as demais DMs, à medida que acontecem, assinadas com o segredo daquela conta e sem manter cópia. send_social_dm responde à pessoa dentro da janela de 24 horas, a partir do Claude, do ChatGPT ou do seu próprio código. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Um evento de menção a Story no Instagram inclui texto?

Não nos exemplos da Meta. Uma menção a Story traz um anexo do tipo story_mention com a URL do CDN do Story, então um handler que lê apenas message.text vê uma mensagem vazia.

O que é link_sticker_url em uma resposta a Story no Instagram?

É a URL da figurinha de link do Story que a pessoa respondeu, em reply_to.story.link_sticker_url. A Meta a adicionou em 12 de dezembro de 2025 e sugere usá-la para rotear automações por link.

Respostas a Story com GIF ou figurinha disparam o webhook?

Não. O guia de Mensagens do Instagram da Meta diz que o webhook não suporta respostas a Story feitas com GIF ou figurinha.

Contas privadas disparam webhooks de menção a Story?

Só quando a conta privada segue a conta profissional. Menções de contas públicas chegam conforme acontecem.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em