# Webhook del ciclo di vita dei messaggi WhatsApp

Ogni passaggio nel [ciclo di vita](/docs/guides/whatsapp/events/lifecycle) di un messaggio può essere inviato al tuo endpoint nel momento in cui avviene. Ogni payload usa l'[evento envelope WhatsApp](/docs/guides/whatsapp/webhooks#the-event-envelope) e contiene i [campi presenti in ogni evento messaggio](/docs/guides/whatsapp/webhooks#fields-every-message-event-carries).

## 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](/docs/guides/whatsapp/events/lifecycle#lifecycle-events) spiega il significato di ciascuno e quando `whatsapp.delivered` viene omesso.

```json
{
  "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](/docs/guides/whatsapp/events/lifecycle#failure-events) 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:

```json
{
  "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](/docs/guides/whatsapp/mark-message-as-read) 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:

```json
{
  "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}`](/docs/api/reference/get-whatsapp-message) documenta ciascuna variante.

## Passaggi successivi

- [Webhook delle reazioni](/docs/guides/whatsapp/webhooks/reactions): le reazioni di un contatto arrivano separatamente
- [Ricevere messaggi WhatsApp](/docs/guides/whatsapp/receiving-whatsapp): tutte le varianti di contenuto e il recupero dei media in entrata
- [Eventi del ciclo di vita](/docs/guides/whatsapp/events/lifecycle): leggere la timeline di un messaggio tramite API

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)