# Ricevere reazioni WhatsApp

Iscriviti alle modifiche delle reazioni per sapere quando un contatto aggiunge un emoji a uno dei tuoi messaggi, la cambia o la rimuove. Le reazioni annotano un messaggio esistente e arrivano tramite `whatsapp.reacted`.

## Prerequisiti

Configura un [endpoint webhook](/docs/guides/webhooks) per il tuo spazio di lavoro. Per recuperare le reazioni correnti o la loro cronologia, usa una chiave API con permesso di lettura WhatsApp.

## 1. Iscriversi alle modifiche delle reazioni

Aggiungi `whatsapp.reacted` alla tua sottoscrizione webhook. Una sottoscrizione a `whatsapp.received` non include le reazioni. Segui la [guida ai webhook](/docs/guides/webhooks) per la verifica della firma, i tentativi di recapito e la configurazione dell'endpoint.

Le reazioni non creano un nuovo messaggio nella lista dei messaggi e non aprono una finestra di assistenza clienti. Se devi rispondere, controlla le [regole della finestra di servizio](/docs/guides/whatsapp/sending-whatsapp) prima di inviare un messaggio in formato libero.

## 2. Identificare il messaggio e la modifica

Leggi `data.whatsapp_id` dell'evento per trovare il messaggio a cui il contatto ha reagito. Si tratta dell'ID messaggio Bird originale (`wam_…`), non di un ID di reazione separato.

Usa `data.from` per identificare il contatto e `data.to` per identificare il tuo mittente WhatsApp. Sono oggetti indirizzo WhatsApp; gestisci gli [ID utente con ambito business](/docs/guides/whatsapp/business-scoped-user-ids) quando l'indirizzo del contatto non ha un numero di telefono.

Un contatto che aggiunge una reazione pollice in su produce questo webhook:

```json
{
  "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"
}
```

Interpreta `data.emoji` come segue:

- Un emoji non null aggiunge o sostituisce la reazione di quel contatto sul messaggio di riferimento.
- Un emoji `null` rimuove la reazione di quel contatto. Il campo è presente in un evento di rimozione.

Una sostituzione arriva come un singolo evento con il nuovo emoji; non esiste un evento di rimozione separato per il vecchio emoji. Conserva la stringa esatta: `❤` e `❤️` sono valori distinti nel payload.

## 3. Recuperare le reazioni correnti

Se la tua applicazione mostra la reazione attualmente associata a un messaggio, [recupera il messaggio](/docs/api/reference/get-whatsapp-message) e leggi il suo `reactions`. La lista contiene una reazione attiva per mittente ed è omessa quando non ci sono reazioni attive.

Per `GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te`, i campi relativi alle reazioni hanno questa struttura (altri campi del messaggio omessi):

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

Il messaggio conserva il contenuto, la direzione e lo stato di consegna originali. `reactions[].from` identifica la persona che ha reagito.

Non trattare l'ultimo webhook ricevuto come lo stato corrente. WhatsApp riporta i tempi di reazione al secondo, quindi le modifiche possono condividere lo stesso timestamp, e i tentativi di recapito dei webhook possono cambiare l'ordine di arrivo. Usa i webhook per attivare un aggiornamento delle reazioni correnti del messaggio.

## 4. Consultare la cronologia delle reazioni

[Elenca gli eventi di reazione](/docs/api/reference/list-whatsapp-message-reaction-events) per esaminare le modifiche al messaggio di riferimento. Le modifiche in ingresso dei contatti hanno stato `received`; una rimozione riporta `emoji: null`. La lista include anche gli esiti delle [reazioni inviate dal tuo spazio di lavoro](/docs/guides/whatsapp/reactions).

L'endpoint reaction-events API restituisce una risposta paginata. Questo esempio mostra una reazione business rifiutata e una precedente reazione di un contatto ricevuta:

```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"
}
```

La cronologia delle reazioni è separata dagli eventi di consegna del messaggio. L'endpoint message-events non contiene le modifiche `whatsapp.reacted`. Per la conservazione e la paginazione, segui il [riferimento al log delle reazioni](/docs/api/reference/list-whatsapp-message-reaction-events).

## Risoluzione dei problemi

- **Nessun webhook di reazione**: verifica che la sottoscrizione includa `whatsapp.reacted`. Una reazione a un messaggio più vecchio il cui riferimento del provider non può più essere risolto non produce alcuna reazione associata, voce di log o webhook.
- **Reazione assente dalla lista dei messaggi**: cerca il messaggio originale. La reazione è associata ad esso e non ha una riga messaggio separata.
- **Lo stato della reazione cambia inaspettatamente**: aggiorna `reactions` del messaggio originale invece di ordinare gli eventi webhook per orario di arrivo o timestamp.

## Passaggi successivi

- [Inviare o rimuovere una reazione](/docs/guides/whatsapp/reactions)
- [Leggere i payload degli eventi WhatsApp](/docs/guides/whatsapp/events)
- [Ricevere messaggi WhatsApp](/docs/guides/whatsapp/receiving-whatsapp)

## 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](/products/whatsapp) (product)

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