Recebendo reações do WhatsApp

Inscreva-se nas alterações de reação para saber quando um contato adiciona um emoji a uma de suas mensagens, altera ou retira. Reações anotam uma mensagem existente e chegam pelo whatsapp.reacted.

Pré-requisitos

Configure um endpoint de webhook para o seu espaço de trabalho. Para recuperar as reações atuais ou o histórico delas, use uma chave API com permissão de leitura WhatsApp.

1. Inscreva-se nas alterações de reação

Adicione whatsapp.reacted à sua assinatura de webhook. Uma assinatura de whatsapp.received não inclui reações. Siga o guia de webhooks para verificação de assinatura, tentativas de entrega e configuração de endpoint.

Reações não criam uma nova mensagem na lista de mensagens nem abrem uma janela de atendimento. Se você precisar responder, verifique as regras de janela de atendimento antes de enviar uma mensagem de formato livre.

2. Identifique a mensagem e a alteração

Leia o data.whatsapp_id do evento para encontrar a mensagem à qual o contato reagiu. Este é o ID de mensagem Bird original (wam_…), e não um ID de reação separado.

Use data.from para identificar o contato e data.to para identificar o seu remetente WhatsApp. Esses são objetos de endereço WhatsApp; trate IDs de usuário com escopo de negócio quando o endereço do contato não tem número de telefone.

Um contato adicionando uma reação de polegar para cima produz este webhook:

Exemplo de código

{
  "data": {
    "emoji": "👍",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-08-28T19:01:10.000Z",
  "type": "whatsapp.reacted"
}

Interprete data.emoji da seguinte forma:

Um emoji não nulo adiciona ou substitui a reação daquele contato na mensagem referenciada.
Um emoji null remove a reação daquele contato. O campo está presente em um evento de remoção.

Uma substituição chega como um único evento contendo o novo emoji; não há um evento de remoção separado para o emoji antigo. Preserve a string exata: ❤ e ❤️ são valores distintos no payload.

3. Recupere as reações atuais

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

Para GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te, os campos relacionados a reação 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.

Não trate o último webhook recebido como o estado atual. WhatsApp informa os horários de reação com precisão de segundo, então alterações podem compartilhar o mesmo timestamp, e tentativas de entrega de webhook podem mudar a ordem de chegada. Use webhooks para disparar uma atualização das reações atuais da mensagem.

4. Inspecione o histórico de reações

Liste eventos de reação para inspecionar alterações na mensagem referenciada. Alterações recebidas de contatos têm status received; uma remoção contém emoji: null. A lista também inclui resultados de reações enviadas pelo seu espaço de trabalho.

O API de eventos de reação retorna uma resposta paginada. Este exemplo mostra uma reação de negócio 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 mensagem não contém alterações de whatsapp.reacted. Para retenção e paginação, consulte a referência do log de reações.

Solução de problemas

Nenhum webhook de reação: Verifique se a assinatura inclui whatsapp.reacted. Uma reação a uma mensagem antiga cuja referência do provedor não pode mais ser resolvida não produz reação correspondente, entrada de log ou webhook.
Reação ausente na lista de mensagens: Consulte a mensagem original. A reação está vinculada a ela e não possui uma linha de mensagem separada.
Estado da reação muda inesperadamente: Atualize o reactions da mensagem original em vez de ordenar eventos de webhook por horário de chegada ou timestamp.

Próximos passos

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