Recibir video de WhatsApp
Un clip que un contacto graba o adjunta llega como un mensaje entrante con video: la misma referencia de medio que usa cada componente de medio entrante, más cualquier descripción que hayan escrito debajo.
Qué contiene un video entrante
Ejemplo de código
{
"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 | Qué contiene |
|---|---|
| id | El archivo almacenado, para pasar como media_id al descargar los bytes |
| url | Una URL Bird, que se obtiene con tu clave API |
| mime_type | El tipo de medio que WhatsApp reportó para el clip, como video/mp4 |
| caption | El texto que el contacto escribió debajo del video; ausente cuando no envió ninguno |
El componente no incluye duración, dimensiones ni miniatura. Lee esos datos del archivo mismo una vez que tengas los bytes, o desde tu propio pipeline de medios.
id y mime_type aparecen solo en un video entrante, ya que Bird obtiene ambos al descargar el archivo. Un video saliente se devuelve con el url que proporcionaste y sin id.
Descargar los bytes
Pasa el ID del mensaje y el id del medio al método de medios del canal. La guía de descarga de medios entrantes incluye esa llamada en todos los lenguajes, junto con las reglas de redirección y encabezados que sigue.
Un video es lo más pesado que un contacto probablemente te envíe, y la descarga sirve los bytes directamente desde el almacenamiento en vez de a través del API, así que transmite la respuesta a disco o a tu propio bucket en lugar de almacenarla en memoria. El mensaje y su medio expiran juntos, 30 días después de que llega el mensaje; la guía de descarga de medios entrantes define esa ventana y lo que devuelven las lecturas una vez que pasa.
El payload del webhook
whatsapp.received incluye el componente video en el sobre del evento:
Ejemplo de código
{
"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
}
}Descarga el clip desde un worker en cola en vez de dentro del handler del webhook: el endpoint tiene que responder rápido, y el medio permanece disponible durante toda la ventana de retención.
Puntos a tener en cuenta
- Una nota de video se lee como un video. La nota de video circular de WhatsApp llega en este componente sin ningún flag que la distinga, a diferencia del audio, donde una nota de voz establece voice.
- Un clip por mensaje. Varios videos llegan como varios mensajes entrantes, cada uno con su propia referencia de medio.
Siguientes pasos
- Cómo funciona la recepción: el sobre del mensaje entrante, la descarga de medios y el webhook whatsapp.received
- Mensajes de video de WhatsApp: el lado de envío del mismo componente
- Recibir audio: notas de voz y archivos de audio adjuntos
- Eventos de WhatsApp: la lista completa de eventos, a través del API o webhooks
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación