# 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

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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:

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp): el sobre del mensaje entrante, la descarga de medios y el webhook `whatsapp.received`
- [Mensajes de documento WhatsApp](/docs/guides/whatsapp/message-types/documents): el lado de envío del mismo brazo
- [Recibir imágenes](/docs/guides/whatsapp/receiving-whatsapp/images): la misma estructura de medios para una foto de un documento
- [Eventos de WhatsApp](/docs/guides/whatsapp/events): la lista completa de eventos, a través de API o webhooks

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)