Recibir documentos de WhatsApp
Un PDF, una hoja de cálculo o cualquier otro archivo que un contacto adjunta llega como un mensaje entrante con document: la referencia de medios compartida, más el nombre que el propio dispositivo del contacto le dio al archivo.
Qué contiene un documento entrante
Ejemplo de código
{
"id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"document": {
"id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
"mime_type": "application/pdf",
"filename": "invoice-A1B2C3.pdf"
},
"created_at": "2026-08-25T09:15:02Z"
}| 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 archivo, por ejemplo application/pdf |
| filename | El nombre que el remitente le dio al archivo; ausente cuando el mensaje no incluyó ninguno |
| caption | El texto que el contacto escribió debajo del documento; ausente cuando no envió ninguno |
filename es el único campo que el lado de envío y el lado de recepción usan de forma distinta: en un envío es el nombre que quieres mostrar en el chat, y en un mensaje entrante es lo que el dispositivo del contacto proporcionó.
Descargar los bytes
Pasa el ID del mensaje y el id de medios al método de medios del canal. La guía del hub sobre descarga de medios entrantes incluye esa llamada en todos los lenguajes, junto con las reglas de redirección y encabezados que sigue, y define la ventana de retención en la que el archivo permanece disponible.
No escribas filename en disco tal como llega. Es texto controlado por un atacante de un remitente no autenticado: puede contener separadores de ruta, secuencias de travesía de directorios, una segunda extensión engañosa o un nombre que colisione con un archivo que ya tienes. Genera tu propia clave de almacenamiento a partir del id de medios, conserva filename como etiqueta de visualización y decide qué hacer con el archivo a partir de mime_type en lugar de la extensión que el nombre declara.
El payload del webhook
whatsapp.received lleva el brazo document en el sobre del evento:
Ejemplo de código
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:15:02.336Z",
"data": {
"whatsapp_id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"document": {
"id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
"mime_type": "application/pdf",
"filename": "invoice-A1B2C3.pdf"
},
"tags": null,
"metadata": null
}
}Un flujo de reclamaciones u onboarding que recopila documentación puede enrutar según mime_type aquí y encolar la descarga, ya que los bytes permanecen disponibles durante toda la ventana de retención.
Puntos a tener en cuenta
- mime_type es lo que WhatsApp reportó sobre el archivo y no dice nada sobre lo que contiene. Analiza todo lo que aceptes de un contacto y valida la estructura propia del archivo antes de procesarlo.
- Un pie de texto y un nombre de archivo son campos distintos. Un contacto que escribe una nota al adjuntar el archivo llena caption; filename sigue viniendo de su dispositivo.
Próximos pasos
- Cómo funciona la recepción: el sobre del mensaje entrante, la descarga de medios y el webhook whatsapp.received
- Mensajes de documento WhatsApp: el lado de envío del mismo brazo
- Recibir imágenes: la misma estructura de medios para una foto de un documento
- Eventos de WhatsApp: la lista completa de eventos, a través de 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