Ricevere video WhatsApp
Un filmato che un contatto registra o allega arriva come messaggio in entrata con video: lo stesso riferimento media usato da ogni ramo media in entrata, più l'eventuale didascalia digitata sotto.
Cosa contiene un video in entrata
Esempio di codice
{
"id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"video": {
"id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
"mime_type": "video/mp4",
"caption": "The rattle starts around 0:12"
},
"created_at": "2026-08-25T09:11:48Z"
}| Campo | Cosa contiene |
|---|---|
| id | Il file archiviato, da passare come media_id per recuperare i byte |
| url | Un URL Bird, da recuperare con la propria chiave API |
| mime_type | Il tipo di media che WhatsApp ha riportato per il filmato, ad esempio video/mp4 |
| caption | Il testo che il contatto ha digitato sotto il video; assente se non ne ha inviato |
Il ramo non contiene durata, dimensioni né miniatura. Ricavarli dal file stesso una volta ottenuti i byte, oppure dalla propria pipeline media.
id e mime_type compaiono solo su un video in entrata, perché Bird li ricava entrambi recuperando il file. Un video in uscita viene restituito con il url fornito e senza id.
Recuperare i byte
Passare l'ID del messaggio e il id del media al metodo media del canale. La sezione recupero dei media in entrata dell'hub riporta quella chiamata in ogni linguaggio, insieme alle regole di redirect e header che segue.
Un video è l'oggetto più grande che un contatto può inviare, e il recupero serve i byte direttamente dallo storage anziché attraverso il API: fare streaming della risposta su disco o nel proprio bucket invece di bufferizzarla. Il messaggio e il suo media scadono insieme, 30 giorni dopo l'arrivo del messaggio; la sezione recupero dei media in entrata dell'hub definisce quella finestra e cosa restituiscono le letture una volta scaduta.
Il payload del webhook
whatsapp.received contiene il ramo video nell'envelope dell'evento:
Esempio di codice
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:11:48.204Z",
"data": {
"whatsapp_id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"video": {
"id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
"mime_type": "video/mp4",
"caption": "The rattle starts around 0:12"
},
"tags": null,
"metadata": null
}
}Recuperare il filmato da un worker in coda anziché all'interno del gestore del webhook: l'endpoint deve rispondere rapidamente, e il media resta disponibile per l'intera finestra di conservazione.
Aspetti da tenere d'occhio
- Una nota video viene letta come un video. La nota video circolare di WhatsApp arriva su questo ramo senza alcun flag che la distingua, a differenza dell'audio, dove una nota vocale imposta voice.
- Un solo filmato per messaggio. Più video arrivano come più messaggi in entrata, ciascuno con il proprio riferimento media.
Passi successivi
- Come funziona la ricezione: l'envelope in entrata, il recupero dei media e il webhook whatsapp.received
- Messaggi video WhatsApp: il lato invio dello stesso ramo
- Ricevere audio: note vocali e file audio allegati
- Eventi WhatsApp: l'elenco completo degli eventi, tramite API o webhook
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