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.

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.

{
  "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 sullo stato dei messaggi: payload di consegna e di errore
• Webhook per i messaggi in entrata: il payload whatsapp.received
• Webhook per le reazioni: il payload whatsapp.reacted
• Guida ai webhook: endpoint, firme, riprovare e il catalogo completo degli eventi