Webhook di stato dei messaggi WhatsApp

Ogni cambio di stato di un messaggio in uscita può essere inviato al tuo endpoint nel momento in cui avviene. Ogni payload usa l'envelope evento WhatsApp e include i campi presenti in ogni evento messaggio.

Eventi di consegna

whatsapp.accepted, whatsapp.sent, whatsapp.delivered e whatsapp.read contengono solo i campi presenti in ogni evento messaggio. Eventi del ciclo di vita spiega il significato di ciascuno e quando whatsapp.delivered viene omesso.

Esempio di codice

{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}

whatsapp.failed e whatsapp.rejected contengono anche un oggetto error con un Bird code stabile, un description leggibile, un meta_error_code opzionale e occurred_at. Vedi eventi di errore per capire cosa distingue i due casi. Quando viene riportato un errore WhatsApp, description è la spiegazione fornita da WhatsApp. Un messaggio di servizio la cui finestra di assistenza clienti si è chiusa tra l'accettazione e l'invio fallisce in questo modo:

Esempio di codice

{
  "data": {
    "direction": "outbound",
    "error": {
      "code": "service_window_expired",
      "description": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "meta_error_code": "131047",
      "occurred_at": "2026-07-23T14:51:40.201Z"
    },
    "from": { "phone_number": "+13124495569" },
    "metadata": null,
    "tags": null,
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:40.201Z",
  "type": "whatsapp.failed"
}

Contrassegnare come letto un messaggio in entrata registra whatsapp.read nella timeline del messaggio, ma non genera un webhook.

Passaggi successivi

Webhook dei messaggi in entrata: il payload whatsapp.received per un messaggio che un contatto ti invia
Webhook delle reazioni: le reazioni di un contatto arrivano separatamente
Eventi di stato dei messaggi: consulta la cronologia di un messaggio tramite la API

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