Webhook WhatsApp
Bird invia l'attività WhatsApp al tuo endpoint in tempo reale, senza bisogno di polling. Iscriviti dalla pagina Webhooks o con POST /v1/webhooks. La guida ai webhook tratta endpoint, verifica della firma e ripetizioni.
Eventi a cui puoi iscriverti
Ogni evento rimanda al proprio payload.
| Evento | Si attiva quando |
|---|---|
| whatsapp.accepted | Bird accetta una richiesta di invio in uscita |
| whatsapp.sent | Bird consegna il messaggio alla rete WhatsApp |
| whatsapp.delivered | WhatsApp conferma la consegna al dispositivo del destinatario |
| whatsapp.read | Il destinatario apre il messaggio |
| whatsapp.failed | Il messaggio non viene consegnato |
| whatsapp.rejected | Bird rifiuta il messaggio prima di inviarlo |
| whatsapp.received | Un contatto ti invia un messaggio |
| whatsapp.reacted | Un contatto aggiunge, modifica o rimuove una reazione |
| whatsapp_suppression.created | Si apre una soppressione nel tuo spazio di lavoro |
| whatsapp.group.join_request_created | Qualcuno chiede di entrare in un gruppo |
| whatsapp.group.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 standard: un type, un timestamp e un oggetto data specifico per il tipo.
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"
}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 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} per vedere quanto è costato.
Prossimi passi
- Webhook del ciclo di vita dei messaggi: payload di consegna e messaggi in entrata
- Eventi del ciclo di vita: leggi la stessa cronologia tramite API
- Guida ai webhook: endpoint, firme, ripetizioni e catalogo completo degli eventi
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