# Ricevere documenti WhatsApp

Un PDF, un foglio di calcolo o qualsiasi altro file allegato da un contatto arriva come messaggio in entrata con `document`: il riferimento al media condiviso, più il nome che il dispositivo del contatto ha assegnato al file.

## Cosa contiene un documento in entrata

```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       | Cosa contiene                                                                                |
| ----------- | -------------------------------------------------------------------------------------------- |
| `id`        | Il file archiviato, da passare come `media_id` quando si scaricano i byte                    |
| `url`       | Un URL Bird, da scaricare con la tua chiave API                                              |
| `mime_type` | Il media type che WhatsApp ha riportato per il file, ad esempio `application/pdf`            |
| `filename`  | Il nome che il mittente ha dato al file; assente quando il messaggio non ne conteneva uno    |
| `caption`   | Il testo che il contatto ha scritto sotto il documento; assente quando non ne ha inviato uno |

`filename` è l'unico campo che il lato di invio e il lato di ricezione usano in modo diverso: in un invio è il nome che vuoi mostrare nella chat, e in un messaggio in entrata è qualsiasi cosa il dispositivo del contatto abbia fornito.

## Scaricare i byte

Passa l'ID del messaggio e il `id` del media al metodo media del canale. La guida [scaricare i media in entrata](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) dell'hub contiene quella chiamata in ogni linguaggio, insieme alle regole di redirect e header che segue, e definisce la finestra di conservazione in cui il file è disponibile.

**Non scrivere `filename` su disco così come arriva.** È testo controllato da un attaccante proveniente da un mittente non autenticato: può contenere separatori di percorso, sequenze di traversal, una seconda estensione fuorviante o un nome che collide con un file già presente. Genera la tua chiave di archiviazione dal `id` del media, conserva `filename` come etichetta di visualizzazione e decidi cosa fare con il file in base a `mime_type` anziché in base all'estensione dichiarata dal nome.

## Il payload del webhook

`whatsapp.received` contiene il ramo `document` nell'envelope dell'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 flusso di richieste o di onboarding che raccoglie documentazione può instradare in base a `mime_type` qui e mettere in coda il download, dato che i byte restano disponibili per l'intera finestra di conservazione.

## Aspetti da tenere d'occhio

- **`mime_type` è il report di WhatsApp sul file, e non dice nulla su cosa contiene.** Scansiona tutto ciò che accetti da un contatto e valida la struttura interna del file prima di analizzarlo.
- **Didascalia e nome file sono campi diversi.** Un contatto che scrive una nota quando allega il file riempie `caption`; `filename` viene comunque dal suo dispositivo.

## Passaggi successivi

- [Come funziona la ricezione](/docs/guides/whatsapp/receiving-whatsapp): l'envelope in entrata, il download dei media e il webhook `whatsapp.received`
- [Messaggi documento WhatsApp](/docs/guides/whatsapp/message-types/documents): il lato di invio dello stesso ramo
- [Ricevere immagini](/docs/guides/whatsapp/receiving-whatsapp/images): la stessa struttura media per la foto di un documento
- [Eventi WhatsApp](/docs/guides/whatsapp/events): l'elenco completo degli eventi, tramite API o webhook

## 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)