Eventi del ciclo di vita dei messaggi WhatsApp
Bird registra eventi per i messaggi WhatsApp in entrata e in uscita. Una cronologia in uscita mostra cosa è successo dopo che un invio ha restituito 202: accettazione, passaggio a WhatsApp, consegna, lettura o errore. Una cronologia in entrata registra quando Bird ha ricevuto il messaggio.
Questa pagina descrive come leggere la cronologia tramite la API. Per fare in modo che Bird invii ogni evento al tuo endpoint nel momento in cui si verifica, consulta Webhook del ciclo di vita dei messaggi. Le reazioni hanno una propria cronologia, descritta in Eventi di reazione.
Eventi del ciclo di vita
Gli eventi compaiono in ordine cronologico. Un messaggio in uscita può fermarsi a whatsapp.failed o whatsapp.rejected, e il suo evento whatsapp.read compare solo se il destinatario apre il messaggio. Una cronologia in entrata inizia con whatsapp.received e può registrare whatsapp.read dopo che il tuo spazio di lavoro segna il messaggio come letto.
| Evento | Significato |
|---|---|
| whatsapp.accepted | Bird ha accettato la richiesta di invio. È il risultato riportato dalla 202. |
| whatsapp.sent | Bird ha passato il messaggio alla rete WhatsApp. |
| whatsapp.delivered | WhatsApp ha confermato la consegna al dispositivo del destinatario. |
| whatsapp.read | Il destinatario ha aperto il messaggio. |
| whatsapp.failed | Il messaggio non è stato consegnato. error.code indica cosa lo ha impedito. |
| whatsapp.rejected | Bird ha rifiutato il messaggio prima di inviarlo. Non è stato addebitato. |
| whatsapp.received | Bird ha ricevuto un messaggio in entrata da un contatto. |
I callback delivered o read applicabili possono attivare la quota di prezzo di Meta. I payload degli eventi WhatsApp non comportano costi. Rileggi il messaggio con GET /v1/whatsapp/messages/{message_id} per vedere quanto è costato. Consulta Costi e fatturazione.
Segnare un messaggio in entrata come letto registra whatsapp.read nella sua cronologia, ma non emette un webhook di conferma lettura. Il messaggio in entrata mantiene il suo stato received e registra read_at dopo che WhatsApp accetta la conferma.
whatsapp.read non modifica il status del messaggio. Un messaggio consegnato resta delivered; il messaggio registra anche la lettura in read_at.
whatsapp.delivered può essere saltato del tutto. Quando il destinatario ha già la chat aperta sul proprio dispositivo, Meta segnala la lettura senza mai segnalare la consegna, quindi la cronologia risulta whatsapp.accepted → whatsapp.sent → whatsapp.read senza whatsapp.delivered nel mezzo. Tratta read come prova di consegna: un consumer che attende delivered prima di considerare il messaggio arrivato si bloccherà proprio sui destinatari che lo hanno visto più velocemente, e uno che calcola il tasso di consegna solo da delivered lo sottostima. Il status del messaggio resta sent in questo caso, perché solo una ricevuta di consegna lo fa avanzare.
Un callback di sola lettura può comunque attivare la tariffa Meta applicabile. Bird usa un'unica identità di tariffa per i percorsi di consegna e lettura; l'assenza dell'evento di consegna non implica una componente Meta gratuita. Consulta Costi e fatturazione.
L'elenco dei tipi di evento è aperto: nuovi tipi possono essere aggiunti nel tempo, quindi tratta un valore non riconosciuto come un evento futuro anziché un errore.
Eventi di errore
whatsapp.failed e whatsapp.rejected sono terminali. Un rifiuto significa che Bird ha bloccato il messaggio prima di inviarlo a WhatsApp, quindi non è stato addebitato. Le cause includono un destinatario soppresso o che ha negato il consenso, saldo del wallet insufficiente o una destinazione senza un prezzo configurato. Un errore significa che il messaggio non è stato consegnato, e error.code indica chi lo ha deciso. La maggior parte dei codici riporta il verdetto di WhatsApp, mappato dal codice che ha segnalato. internal_error è l'eccezione: registra la mancanza di credenziali del mittente utilizzabili o i tentativi di elaborazione esauriti. Un tentativo di trasporto incerto non dimostra che Meta non abbia mai ricevuto la richiesta. meta_error_code contiene il codice di WhatsApp quando disponibile, e un errore internal_error non ne ha per definizione.
Entrambi gli eventi contengono un oggetto error con un Bird code stabile, un description leggibile, un meta_error_code opzionale e occurred_at. L'oggetto compare nei record API e nei payload dei webhook solo per questi tipi di evento.
Leggere gli eventi dalla API
GET /v1/whatsapp/messages/{message_id}/events restituisce la cronologia in ordine cronologico. La lista limitata non è paginata. Leggere gli eventi richiede una chiave API con whatsapp:read:
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);events = client.whatsapp.list_events("wa_abc123")
for event in events.data:
print(event.type, event.occurred_at)events, err := client.Whatsapp.ListEvents(context.Background(), "wam_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappListEventsParams{})
if err != nil {
log.Fatal(err)
}
for _, e := range events.Data {
fmt.Println(e.Id, e.Type)
}$events = $bird->whatsapp->listEvents('wamid_01krdgeqcxet5s7t44vh8rt9mg');
foreach ($events->getData() ?? [] as $event) {
echo $event->getType(), ' ', $event->getId(), "\n";
}bird whatsapp list-events <message-id>curl https://us1.platform.bird.com/v1/whatsapp/messages/wam_.../events \
-H "Authorization: Bearer $BIRD_API_KEY"Un messaggio accettato, inviato, consegnato e letto restituisce quattro eventi:
Esempio di codice
{
"data": [
{
"id": "ev_01ky7q6a1fejfbvs0myn41hj41",
"occurred_at": "2026-07-23T14:48:34.71Z",
"type": "whatsapp.accepted"
},
{
"id": "ev_01ky7q6a2denvtd6jg1vqwmg13",
"occurred_at": "2026-07-23T14:48:35.671Z",
"type": "whatsapp.sent"
},
{
"id": "ev_01ky7q6a2zff9r2qm74mmg1g6z",
"occurred_at": "2026-07-23T14:48:36.642Z",
"type": "whatsapp.delivered"
},
{
"id": "ev_01ky7q6c21frssf0vj8h50qysw",
"occurred_at": "2026-07-23T14:48:38.65Z",
"type": "whatsapp.read"
}
]
}Passa type per restituire un singolo tipo di evento pubblico, come ?type=whatsapp.failed o ?type=whatsapp.read. Omettilo per la cronologia completa.
La stessa cronologia è ciò che la pagina Log WhatsApp visualizza quando apri un messaggio.
Passaggi successivi
- Webhook del ciclo di vita dei messaggi: ricevi ogni evento nel momento in cui si verifica
- Eventi di reazione: leggi le reazioni correnti e il log delle reazioni
- Segna messaggio come letto: conferma un messaggio in entrata e mostra la digitazione
- Log WhatsApp: la vista per messaggio che visualizza questa cronologia
- Invio di messaggi WhatsApp: dove inizia il ciclo di vita 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 channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione