# Messaggi documento WhatsApp Un messaggio documento trasporta un URL pubblico che WhatsApp recupera al momento dell'invio, con una didascalia facoltativa e un nome file facoltativo. È il tipo di media più grande e l'unico che trasporta sia una didascalia sia un nome file. ## Inviare un documento Imposta `document.url`: **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "+16505551234", from: "+13124495648", document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" }, }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/documents.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/documents.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/documents.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/documents.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/documents.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/documents.curl.md) La forma completa aggiunge `caption` e `filename`: ```json { "to": "+16505551234", "from": "+13124495648", "document": { "url": "https://cdn.example.com/invoices/a1b2c3.pdf", "caption": "Your invoice for order A1B2C3", "filename": "invoice-a1b2c3.pdf" } } ``` `from` è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. ## Limiti | Campo | Vincolo | Applicato da | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | Dimensione file | 100 MB | Solo WhatsApp, al fetch (asincrono) | | Tipo di file | PDF, Word, Excel, PowerPoint o testo semplice vengono visualizzati in modo affidabile nel client WhatsApp; gli altri tipi vengono trasmessi ma non sono supportati | Solo WhatsApp, al fetch (asincrono) | | `caption` | Fino a 1024 caratteri | Bird, all'accettazione (`422`) | | `filename` | Da 1 a 100 caratteri | Bird, all'accettazione (`422`); questo limite è una scelta di Bird, dato che WhatsApp non documenta alcun limite per il nome file | | `url` | Assoluto, `https`, con host, senza spazi grezzi | Bird, all'accettazione (`422`) | Bird controlla la forma dell'URL e la lunghezza della didascalia e del nome file prima di accodare qualsiasi cosa. Non controlla la dimensione o il tipo effettivi del file; solo il fetch di WhatsApp al momento dell'invio può farlo. Consulta le pagine dell'hub [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url) e [quando un media fallisce](/docs/guides/whatsapp/message-types#when-media-fails). ## Leggere un documento in ingresso Un documento in ingresso trasporta lo stesso oggetto `document`, più un `id` e un `mime_type` che Bird ha appreso recuperando il file. Entrambi sono assenti in una rilettura in uscita, perché Bird non ha mai recuperato il file che ha inviato, e `filename` in un documento in ingresso è qualsiasi valore fornito dal dispositivo del contatto. Consulta [Ricezione di documenti WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/documents) per la lettura completa in ingresso, il payload `whatsapp.received` e gli aspetti a cui prestare attenzione. ## Limiti e modalità di errore - **La finestra del servizio clienti deve essere aperta.** I documenti sono messaggi di servizio, recapitabili solo all'interno di una finestra aperta; consulta la pagina dell'hub [finestra del servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird rifiuta `http`; WhatsApp stesso lo recupererebbe.** Consulta la pagina dell'hub [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url) per il controllo completo della forma. - **Un fetch rifiutato viene comunque addebitato, e questo è il tipo di media che più probabilmente lo incontra.** Con 100 MB, un documento è l'elemento più grande che puoi inviare, e Bird non controlla nulla sui byte effettivi all'accettazione. Consulta la pagina dell'hub [quando un media fallisce](/docs/guides/whatsapp/message-types#when-media-fails) per `media_rejected` e il fatto che l'addebito avviene anche in caso di errore. Il testo di rifiuto specifico per i documenti da parte di WhatsApp non è stato misurato in modo indipendente come per le immagini, quindi considera la mappatura come inferita per simmetria piuttosto che confermata per ogni causa. - **Omettere `filename` non significa che il destinatario non veda alcun nome.** WhatsApp ne ricava uno dal percorso dell'URL, che può essere un hash opaco o uno slug anziché qualcosa di leggibile. Imposta `filename` esplicitamente per controllare ciò che viene effettivamente mostrato. - **Il limite di 100 caratteri per `filename` è una scelta di Bird, non un limite di WhatsApp.** WhatsApp non documenta alcun limite di lunghezza per il nome file. - **WhatsApp mette in cache un URL recuperato per circa 10 minuti.** Reinviare lo stesso URL all'interno di quella finestra serve il primo fetch; modifica l'URL per forzarne uno nuovo. ## Passaggi successivi - [Messaggi di servizio WhatsApp](/docs/guides/whatsapp/message-types): la finestra del servizio clienti e il modello condiviso da ogni messaggio di servizio - [Immagini](/docs/guides/whatsapp/message-types/images): per una foto o un elemento grafico al posto di un file - [Template](/docs/guides/whatsapp/templates): per i messaggi da inviare quando la finestra è chiusa - [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la struttura della richiesta, il modello `202` e i tentativi sicuri di riprovare ## 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)