# Mensagens de documento WhatsApp Uma mensagem de documento carrega uma URL pública que WhatsApp busca no momento do envio, com uma legenda opcional e um nome de arquivo opcional. É o maior tipo de mídia, e o único que carrega tanto uma legenda quanto um nome de arquivo. ## Enviar um documento Defina `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](/pt-br/documentacao/guides/whatsapp/message-types/documents.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/message-types/documents.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/message-types/documents.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/message-types/documents.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/message-types/documents.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/message-types/documents.curl.md) A forma completa adiciona `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` é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado por Bird. ## Limites | Campo | Limite | Aplicado por | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | Tamanho do arquivo | 100 MB | Apenas WhatsApp, na busca (async) | | Tipo de arquivo | PDF, Word, Excel, PowerPoint ou texto simples renderizam de forma confiável no cliente WhatsApp; outros tipos são transmitidos, mas não são suportados | Apenas WhatsApp, na busca (async) | | `caption` | até 1.024 caracteres | Bird, no aceite (`422`) | | `filename` | 1 a 100 caracteres | Bird, no aceite (`422`); esse limite é do próprio Bird, já que WhatsApp não documenta limite de nome de arquivo | | `url` | absoluta, `https`, tem host, sem espaço bruto | Bird, no aceite (`422`) | Bird verifica o formato da URL e o comprimento da legenda e do nome de arquivo antes de qualquer coisa ser enfileirada. Ele não verifica o tamanho nem o tipo real do arquivo; apenas a busca do próprio WhatsApp no momento do envio pode fazê-lo. Consulte no hub [envio de mídia por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) e [quando a mídia falha](/docs/guides/whatsapp/message-types#when-media-fails). ## Leitura de um documento recebido Um documento recebido carrega o mesmo objeto `document`, além de um `id` e `mime_type` que Bird aprendeu ao buscar o arquivo. Ambos estão ausentes em uma leitura de mensagem enviada, já que Bird nunca buscou o arquivo que enviou, e `filename` em um documento recebido é o que o dispositivo do contato forneceu. Consulte [Recebendo documentos WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/documents) para a leitura completa do recebimento, o payload `whatsapp.received` e o que observar. ## Limites e modos de falha - **A janela de atendimento ao cliente precisa estar aberta.** Documentos são mensagens de serviço, entregáveis apenas dentro de uma janela aberta; consulte no hub a [janela de atendimento ao cliente](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird rejeita `http`; WhatsApp em si buscaria o arquivo.** Consulte no hub o [envio de mídia por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) para a verificação completa de formato. - **Uma busca rejeitada ainda é cobrada, e este é o tipo de mídia com maior probabilidade de encontrar isso.** Com 100 MB, um documento é a maior coisa que você pode enviar, e Bird não verifica nada sobre os bytes reais no aceite. Consulte no hub [quando a mídia falha](/docs/guides/whatsapp/message-types#when-media-fails) para `media_rejected` e o fato da cobrança em caso de falha. O texto de rejeição específico de documento vindo de WhatsApp não foi medido de forma independente como o de imagem, então trate o mapeamento como inferido por simetria e não confirmado por causa. - **Omitir `filename` não significa que o destinatário não verá nenhum nome.** WhatsApp deriva um nome a partir do caminho da URL, que pode ser um hash opaco ou slug em vez de algo legível. Defina `filename` explicitamente para controlar o que realmente aparece. - **O limite de 100 caracteres de `filename` é uma escolha do próprio Bird, não um limite de WhatsApp.** WhatsApp não documenta nenhum limite de comprimento de nome de arquivo. - **WhatsApp mantém em cache uma URL buscada por cerca de 10 minutos.** Reenviar a mesma URL dentro dessa janela serve novamente a primeira busca; varie a URL para forçar uma nova. ## Próximos passos - [Mensagens de serviço WhatsApp](/docs/guides/whatsapp/message-types): a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha - [Imagens](/docs/guides/whatsapp/message-types/images): para uma foto ou gráfico em vez de um arquivo - [Templates](/docs/guides/whatsapp/templates): para mensagens que você pode enviar depois que a janela for fechada - [Envio de mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): a estrutura da solicitação, o modelo `202` e tentativas seguras de reenvio ## 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)