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 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 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 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 quando l'indirizzo del contatto non ha un numero di telefono.

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

Esempio di codice

{
  "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 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):

Esempio di codice

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

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

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

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.

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

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