Eventos de reação WhatsApp

Uma reação com emoji anota uma mensagem existente em vez de criar uma nova, então ela nunca aparece como uma mensagem própria nem nos eventos de ciclo de vida da mensagem. Bird mantém duas visões dela: as reações presentes na mensagem agora e um registro de cada alteração que levou até ali. Ambas registram alterações feitas pelo contato e pelo seu número comercial.

Para ser notificado sobre a reação de um contato no momento em que ela acontece, inscreva-se em whatsapp.reacted. Para adicionar ou remover a sua própria, veja Enviando reações.

Pré-requisitos

Uma chave API com permissão de leitura WhatsApp e o ID (wam_…) da mensagem que recebeu a reação.

1. Leia as reações atuais

Se a sua aplicação exibe a reação atualmente anexada a uma mensagem, recupere a mensagem e leia seu reactions. A lista contém uma reação vigente por remetente e é omitida quando não há reações.

Para GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te, os campos relacionados a reações têm este formato (outros campos da mensagem omitidos):

Exemplo de código

{
  "id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
  "reactions": [
    {
      "emoji": "👍",
      "from": { "phone_number": "+14155550100" }
    }
  ]
}

A mensagem mantém seu conteúdo, direção e status de entrega originais. reactions[].from identifica a pessoa que reagiu.

Este é o estado a ser exibido. Webhooks de reação podem compartilhar um timestamp e chegar fora de ordem, então use um como gatilho para ler a mensagem novamente em vez de usá-lo como o estado atual.

2. Leia o registro de reações

Liste eventos de reação com GET /v1/whatsapp/messages/{message_id}/reaction-events para ver cada alteração na mensagem referenciada, da mais recente para a mais antiga: adições, substituições e remoções. Cada entrada tem um ID de reação (war_…), o emoji, quem fez a alteração em from, um timestamp occurred_at e um status:

received: alteração de um contato.
sent: WhatsApp aceitou uma alteração do seu número comercial.
failed: WhatsApp recusou sua alteração.
rejected: Bird recusou sua alteração antes de enviá-la.

Uma entrada failed ou rejected traz o motivo em error. Uma remoção traz emoji: null. Uma alteração sua que ainda está pendente não tem entrada até que o resultado seja conhecido. Uma reação nunca é cobrada, então nenhuma falha aqui é de cobrança.

O API de eventos de reação retorna uma resposta paginada. Este exemplo mostra uma reação comercial rejeitada e uma reação de contato recebida anteriormente:

Exemplo de código

{
  "data": [
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mh",
      "emoji": "🎉",
      "status": "rejected",
      "from": {
        "phone_number": "+13124495569"
      },
      "error": {
        "code": "internal_error",
        "description": "the receiving number is no longer connected",
        "occurred_at": "2026-08-28T19:04:22Z"
      },
      "occurred_at": "2026-08-28T19:04:22Z"
    },
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mg",
      "emoji": "👍",
      "status": "received",
      "from": {
        "phone_number": "+14155550100",
        "bsuid": "US.13491208655302741918"
      },
      "occurred_at": "2026-08-28T19:01:10Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0"
}

O histórico de reações é separado dos eventos de entrega da mensagem. O endpoint de eventos de ciclo de vida não contém alterações de whatsapp.reacted. Para retenção e paginação, siga a referência do registro de reações.

Solução de problemas

Reação ausente na lista de mensagens: Consulte a mensagem original. Uma reação está anexada a ela e não tem uma linha de mensagem separada.
Estado da reação muda inesperadamente: Leia o reactions da mensagem em vez de ordenar eventos de webhook por hora de chegada ou timestamp.

Próximos passos

Webhooks de reação: seja notificado quando um contato reagir
Enviar ou remover uma reação
Eventos de ciclo de vida: a linha do tempo de entrega de uma mensagem

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação