# Webhook WhatsApp

Bird invia l'attività WhatsApp al tuo endpoint in tempo reale, senza bisogno di polling. Iscriviti dalla pagina [**Webhooks**](https://bird.com/dashboard/w/webhooks) o con [`POST /v1/webhooks`](/docs/api/reference/create-webhook). La [guida ai webhook](/docs/guides/webhooks) tratta endpoint, verifica della firma e ripetizioni.

## Eventi a cui puoi iscriverti

Ogni evento rimanda al proprio payload.

| Evento                                                                                              | Si attiva quando                                              |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`whatsapp.accepted`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird accetta una richiesta di invio in uscita                 |
| [`whatsapp.sent`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | Bird consegna il messaggio alla rete WhatsApp                 |
| [`whatsapp.delivered`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                    | WhatsApp conferma la consegna al dispositivo del destinatario |
| [`whatsapp.read`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | Il destinatario apre il messaggio                             |
| [`whatsapp.failed`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                       | Il messaggio non viene consegnato                             |
| [`whatsapp.rejected`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird rifiuta il messaggio prima di inviarlo                   |
| [`whatsapp.received`](/docs/guides/whatsapp/webhooks/lifecycle#incoming-messages)                   | Un contatto ti invia un messaggio                             |
| [`whatsapp.reacted`](/docs/guides/whatsapp/webhooks/reactions)                                      | Un contatto aggiunge, modifica o rimuove una reazione         |
| [`whatsapp_suppression.created`](/docs/guides/whatsapp/webhooks/suppressions)                       | Si apre una soppressione nel tuo spazio di lavoro             |
| [`whatsapp.group.join_request_created`](/docs/guides/whatsapp/webhooks/groups#join-request-created) | Qualcuno chiede di entrare in un gruppo                       |
| [`whatsapp.group.join_request_revoked`](/docs/guides/whatsapp/webhooks/groups#join-request-revoked) | Qualcuno annulla la richiesta di entrare in un gruppo         |

L'elenco dei tipi di evento è aperto: nuovi tipi possono essere aggiunti nel tempo, quindi tratta un valore non riconosciuto come un evento futuro, non come un errore.

## L'envelope dell'evento

Ogni evento WhatsApp usa l'[envelope webhook](/docs/guides/webhooks) standard: un `type`, un `timestamp` e un oggetto `data` specifico per il tipo.

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

## Campi presenti in ogni evento messaggio

Ogni payload webhook WhatsApp per un messaggio contiene `whatsapp_id`, `workspace_id`, `direction`, `from`, `to`, `tags` e `metadata`. Gli eventi di reazione, soppressione e gruppo non riguardano un messaggio, quindi ognuno ha una struttura propria, descritta nella rispettiva pagina.

- **Indirizzi**: `from` e `to` possono includere un `phone_number` E.164, un [ID utente business-scoped](/docs/guides/whatsapp/business-scoped-user-ids) Meta in `bsuid`, o entrambi. Un messaggio ricevuto da un utente WhatsApp contiene anche il profilo che pubblica, in `username` e `display_name`.
- **`tags` e `metadata`** sono `null` quando l'invio non ne conteneva.
- **`in_reply_to_message_id`** compare in ogni evento in uscita di un messaggio inviato come risposta, da `whatsapp.accepted` fino a `whatsapp.read`, `whatsapp.failed` o `whatsapp.rejected`, indicando il messaggio a cui risponde.

I payload degli eventi non contengono costi. Recupera il messaggio con [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) per vedere quanto è costato.

## Prossimi passi

- [Webhook del ciclo di vita dei messaggi](/docs/guides/whatsapp/webhooks/lifecycle): payload di consegna e messaggi in entrata
- [Eventi del ciclo di vita](/docs/guides/whatsapp/events/lifecycle): leggi la stessa cronologia tramite API
- [Guida ai webhook](/docs/guides/webhooks): endpoint, firme, ripetizioni e catalogo completo degli eventi

## 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)