# 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](/docs/guides/whatsapp/events/lifecycle) 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`](/docs/guides/whatsapp/webhooks/reactions). Para adicionar ou remover a sua própria, veja [Enviando reações](/docs/guides/whatsapp/reactions).

## 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](/docs/api/reference/get-whatsapp-message) 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):

```json
{
  "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](/docs/guides/whatsapp/webhooks/reactions) 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](/docs/api/reference/list-whatsapp-message-reaction-events) 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](/docs/guides/whatsapp/reactions).
- `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:

```json
{
  "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](/docs/guides/whatsapp/events/lifecycle) não contém alterações de `whatsapp.reacted`. Para retenção e paginação, siga a [referência do registro de reações](/docs/api/reference/list-whatsapp-message-reaction-events).

## 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](/docs/guides/whatsapp/webhooks/reactions): seja notificado quando um contato reagir
- [Enviar ou remover uma reação](/docs/guides/whatsapp/reactions)
- [Eventos de ciclo de vida](/docs/guides/whatsapp/events/lifecycle): a linha do tempo de entrega de uma mensagem

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)