EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Webhook message_reactions do Instagram: o payload de reagir e de remover a reação

O campo message_reactions do webhook do Instagram notifica um app quando uma pessoa reage a uma mensagem na conversa dela com uma conta profissional, ou remove a reação. O evento fica no array messaging, com um objeto reaction: mid, o ID da mensagem reagida; action, react ou unreact; e, somente em um react, reaction, como love, e emoji, o próprio emoji.

O easyCoexistence inscreve cada conta do Instagram conectada em comments, messages e mentions e encaminha esses eventos ao seu endpoint HTTPS assim que chegam, assinados com o segredo daquela conta, cada mensagem com seu mid.

react / unreact

Os dois valores de reaction.action: uma reação adicionada, ou uma reação removida.

v12.0

Versão da Graph API a partir da qual a Meta oferece suporte a angry, sad, wow, love, like, laugh e outras reações neste webhook.

No echo

A Meta não envia notificação quando a própria conta reage ou remove a reação a uma mensagem de uma pessoa.

Default

message_reactions está entre os campos aos quais um novo produto do Instagram no App Dashboard já começa inscrito.

100/sec

Chamadas da Send API por segundo por conta, para texto, links, reações e figurinhas.

Quando message_reactions é disparado?

Quando uma pessoa reage a uma mensagem na conversa dela com a conta profissional, e de novo quando remove essa reação, desde que o app e a conta estejam inscritos no campo. O guia de Mensagens do Instagram da Meta é explícito na outra direção: quando a própria conta reage ou remove uma reação, nenhuma notificação é enviada, e messages também não entrega echo para ela.

Como é uma notificação de reação?

Um POST com object definido como instagram, cujo entry contém um array messaging. Diferente de uma DM, o evento não traz objeto message: a reação fica no seu próprio objeto reaction, ao lado de sender, recipient e timestamp. Exemplo da Meta para o Instagram Login:

A message_reactions notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "reaction": {
            "mid": "<MESSAGE_ID>",
            "action": "react",
            "reaction": "love",
            "emoji": "\u{2764}\u{FE0F}"
          }
        }
      ]
    }
  ]
}

O que significa cada campo?

Os campos que a Meta documenta para um evento de reação, de fora para dentro:

  • entry[].id e recipient.id: a conta profissional. sender.id: o ID com escopo do Instagram da pessoa que reagiu.
  • timestamp: quando o evento foi disparado, em milissegundos nos exemplos da Meta; entry[].time é quando a Meta enviou a notificação.
  • reaction.mid: o ID da mensagem reagida, o mesmo mid que essa mensagem tinha no seu evento messages.
  • reaction.action: react quando uma reação é adicionada, unreact quando ela é removida.
  • reaction.reaction: o nome da reação, como love; a Meta lista angry, sad, wow, love, like, laugh e other.
  • reaction.emoji: o emoji como string Unicode, como \u{2764}\u{FE0F} para love.
  • Em unreact, reaction e emoji são omitidos.

Como é um unreact?

O mesmo evento com action definido como unreact e sem reaction nem emoji, já que não há nada a nomear. Associe-o à reação que ele remove por reaction.mid e sender.id, e retire a reação dessa pessoa da mensagem nos seus registros.

The reaction object of an unreact
"reaction": {
  "mid": "<MESSAGE_ID>",
  "action": "unreact"
}

Para qual mensagem aponta o mid?

Para a mensagem que a pessoa reagiu, sob o mesmo mid que ela tinha no seu evento messages, incluindo os echos das próprias mensagens da conta. Um handler que armazena mids pode vincular a reação à linha certa da conversa. A Meta aponta uma lacuna: uma reação a uma imagem de um post em carrossel informa a primeira imagem do carrossel, que pode não ser a escolhida.

Como uma conta reage a uma mensagem?

Com POST /<IG_ID>/messages: recipient.id definido como o ID com escopo do Instagram da pessoa, sender_action definido como react e um payload com message_id e reaction, um emoji ou sua forma UTF-8. Repetir a chamada com outro emoji troca a reação, e sender_action definido como unreact com apenas message_id a remove. Nenhuma das duas chamadas gera webhook.

Reacting to a person's message
POST https://graph.instagram.com/<IG_ID>/messages
Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json

{
  "recipient": { "id": "<IGSID>" },
  "sender_action": "react",
  "payload": {
    "message_id": "<MESSAGE_ID>",
    "reaction": "<EMOJI>"
  }
}

O que message_reactions exige?

Com o Instagram Login, instagram_business_basic e instagram_business_manage_messages, e Advanced Access para contas que o desenvolvedor não possui nem gerencia. Um novo produto do Instagram no App Dashboard começa inscrito em message_reactions, e cada conta se inscreve por POST /<IG_ID>/subscribed_apps. O guia Send Messages da Meta lista o campo como messaging_reactions, mas sua tabela de campos, os padrões do dashboard e a referência de webhook dizem message_reactions.

O easyCoexistence encaminha reações?

Não. O app do easyCoexistence e cada conta conectada são inscritos apenas em comments, messages e mentions, então eventos message_reactions não são encaminhados ao seu endpoint. As DMs e os ecos que as reações apontam pelo mid chegam ao seu endpoint, assinados com o segredo da conta.

Erros comuns

  • Procurar a reação dentro de message. Um evento de reação não tem objeto message; leia o objeto reaction ao lado de sender e recipient.
  • Ler reaction ou emoji sem verificar action. Ambos são omitidos em unreact, então código que presume a presença deles quebra quando uma reação é removida.
  • Esperar um webhook depois que a conta reage. A Meta não envia nenhum para as reações da própria conta, nem mesmo um echo, então registre-as quando o seu app as enviar.
  • Copiar o nome messaging_reactions do guia Send Messages da Meta. O campo na sua tabela de campos, nos padrões do dashboard e na referência de webhook é message_reactions.
Fazendo isso com o EasyCoexistence

Seu agente responde a uma pessoa com send_social_dm dentro da janela de 24 horas. 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

Por que uma reação em um post de carrossel aponta para a primeira imagem?

A Meta informa a primeira imagem do carrossel quando alguém reage a uma das imagens dele, que pode não ser a imagem escolhida pela pessoa.

O Instagram envia um webhook quando a empresa reage a uma mensagem?

Não. A Meta não envia notificação message_reactions nem echo quando a conta reage ou remove a reação a uma mensagem.

Quais reações o webhook do Instagram pode informar?

O guia de Mensagens do Instagram da Meta lista angry, sad, wow, love, like, laugh e other a partir da Graph API v12.0, com o próprio emoji em reaction.emoji.

O nome do campo do webhook é message_reactions ou messaging_reactions?

message_reactions. O guia Send Messages da Meta escreve messaging_reactions, mas a tabela de campos, os padrões do App Dashboard e a referência de webhook usam message_reactions.

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