Eventi di reazione WhatsApp

Una reazione emoji annota un messaggio esistente anziché crearne uno nuovo, quindi non compare mai come messaggio a sé stante né negli eventi del ciclo di vita del messaggio. Bird ne conserva invece due viste: le reazioni attualmente presenti sul messaggio e un registro di ogni modifica che le ha prodotte. Entrambe registrano le modifiche del contatto e del tuo numero aziendale.

Per ricevere una notifica sulla reazione di un contatto nel momento in cui avviene, iscriviti a whatsapp.reacted. Per aggiungere o rimuovere le tue reazioni, consulta Invio di reazioni.

Prerequisiti

Una chiave API con permesso di lettura WhatsApp e l'ID (wam_…) del messaggio a cui è stata aggiunta la reazione.

1. Leggere le reazioni correnti

Se la tua applicazione mostra la reazione attualmente associata a un messaggio, recupera il messaggio e leggi il suo reactions. L'elenco contiene una reazione attiva per mittente e viene omesso quando non sono presenti reazioni.

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

Esempio di codice

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

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

Questo è lo stato da visualizzare. I webhook delle reazioni possono condividere un timestamp e arrivare fuori ordine: usali come trigger per rileggere il messaggio, non come stato corrente.

2. Leggere il registro delle reazioni

Elenca gli eventi di reazione con GET /v1/whatsapp/messages/{message_id}/reaction-events per vedere ogni modifica al messaggio di riferimento, dalla più recente: aggiunte, sostituzioni e rimozioni. Ogni voce ha un ID reazione (war_…), il emoji, chi ha effettuato la modifica in from, un timestamp occurred_at e un status:

received: modifica di un contatto.
sent: WhatsApp ha accettato una modifica del tuo numero aziendale.
failed: WhatsApp ha rifiutato la tua modifica.
rejected: Bird ha rifiutato la tua modifica prima dell'invio.

Una voce failed o rejected riporta il motivo in error. Una rimozione riporta emoji: null. Una tua modifica ancora in sospeso non ha alcuna voce finché il risultato non è noto. Una reazione non viene mai addebitata, quindi nessun errore qui è di fatturazione.

L'API degli eventi di reazione restituisce una risposta paginata. Questo esempio mostra una reazione aziendale rifiutata e una precedente reazione ricevuta da un contatto:

Esempio di codice

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

Lo storico delle reazioni è separato dagli eventi di consegna del messaggio. L'endpoint degli eventi del ciclo di vita non contiene le modifiche whatsapp.reacted. Per la conservazione e la paginazione, segui il riferimento al registro delle reazioni.

Risoluzione dei problemi

Reazione assente dall'elenco dei messaggi: cerca il messaggio originale. Una reazione è associata a quel messaggio e non ha una riga messaggio separata.
Lo stato della reazione cambia inaspettatamente: leggi il reactions del messaggio anziché ordinare gli eventi webhook per orario di arrivo o timestamp.

Passaggi successivi

Webhook delle reazioni: ricevi una notifica quando un contatto reagisce
Invia o rimuovi una reazione
Eventi del ciclo di vita: la cronologia di consegna di un messaggio

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione