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

Esempio di codice

{
  "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 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:

Esempio di codice

{
  "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: l'envelope in entrata, il download dei media e il webhook whatsapp.received
Messaggi documento WhatsApp: il lato di invio dello stesso ramo
Ricevere immagini: la stessa struttura media per la foto di un documento
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 channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione