Webhook del ciclo di vita dei messaggi WhatsApp

Ogni passaggio nel ciclo di vita di un messaggio può essere inviato al tuo endpoint nel momento in cui avviene. Ogni payload usa l'evento envelope WhatsApp e contiene 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. Consulta eventi di errore per capire cosa distingue i due casi. In un errore segnalato da 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.

Messaggi in entrata

whatsapp.received include il contenuto del messaggio oltre ai campi presenti in ogni evento messaggio, così un endpoint può agire su un messaggio in entrata senza doverlo rileggere. Un tap su un messaggio interattivo arriva come interactive_reply, e in_reply_to_message_id indica il messaggio a cui risponde:

Esempio di codice

{
  "data": {
    "direction": "inbound",
    "from": {
      "display_name": "Alex Rivera",
      "phone_number": "+14155550100",
      "username": "alexr"
    },
    "in_reply_to_message_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "interactive_reply": {
      "list": {
        "description": "Next day to 2 days",
        "slug": "priority_express",
        "text": "Priority Mail Express"
      },
      "type": "list"
    },
    "metadata": null,
    "tags": null,
    "to": { "phone_number": "+13124495569" },
    "whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:52:04.118Z",
  "type": "whatsapp.received"
}

Le altre varianti di contenuto seguono la stessa struttura a scelta singola: text, image, video, audio, sticker, document, location, contact_cards e unsupported per un tipo non modellato da API. GET /v1/whatsapp/messages/{message_id} documenta ciascuna variante.

Passaggi successivi

Webhook delle reazioni: le reazioni di un contatto arrivano separatamente
Ricevere messaggi WhatsApp: tutte le varianti di contenuto e il recupero dei media in entrata
Eventi del ciclo di vita: leggere la timeline di un messaggio tramite 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