# Mensajes de documento de WhatsApp Un mensaje de documento lleva una URL pública que WhatsApp obtiene en el momento del envío, con un pie de texto opcional y un nombre de archivo opcional. Es el tipo de medio más grande, y el único que admite tanto un pie de texto como un nombre de archivo. ## Enviar un documento Establece `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](/es-es/documentacion/guides/whatsapp/message-types/documents.ts.md) · [Python](/es-es/documentacion/guides/whatsapp/message-types/documents.py.md) · [Go](/es-es/documentacion/guides/whatsapp/message-types/documents.go.md) · [PHP](/es-es/documentacion/guides/whatsapp/message-types/documents.php.md) · [CLI](/es-es/documentacion/guides/whatsapp/message-types/documents.cli.md) · [MCP](/es-es/documentacion/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/es-es/documentacion/guides/whatsapp/message-types/documents.curl.md) La forma completa añade `caption` y `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` es obligatorio en cada mensaje de servicio: un número que tu espacio de trabajo posee, no uno gestionado por Bird. ## Límites | Campo | Límite | Aplicado por | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Tamaño de archivo | 100 MB | Solo WhatsApp, al obtener el archivo (async) | | Tipo de archivo | PDF, Word, Excel, PowerPoint o texto plano se muestran de forma fiable en el cliente de WhatsApp; otros tipos se transmiten pero no están soportados | Solo WhatsApp, al obtener el archivo (async) | | `caption` | hasta 1024 caracteres | Bird, al aceptar (`422`) | | `filename` | de 1 a 100 caracteres | Bird, al aceptar (`422`); este tope es propio de Bird, ya que WhatsApp no documenta ningún límite de nombre de archivo | | `url` | absoluta, `https`, con host, sin espacios en crudo | Bird, al aceptar (`422`) | Bird comprueba la forma de la URL y la longitud del pie de texto y del nombre de archivo antes de encolar nada. No comprueba el tamaño ni el tipo real del archivo; solo la obtención propia de WhatsApp en el momento del envío puede hacerlo. Consulta en el hub [enviar medios por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) y [cuando un medio falla](/docs/guides/whatsapp/message-types#when-media-fails). ## Leer un documento entrante Un documento entrante lleva el mismo objeto `document`, más un `id` y `mime_type` que Bird obtuvo al descargar el archivo. Ambos están ausentes en la lectura de un mensaje saliente, ya que Bird nunca descargó el archivo que envió, y `filename` en uno entrante es lo que proporcionó el dispositivo del contacto. Consulta [Recibir documentos de WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/documents) para la lectura entrante completa, el payload `whatsapp.received` y qué tener en cuenta. ## Límites y modos de fallo - **La ventana de servicio al cliente debe estar abierta.** Los documentos son mensajes de servicio, entregables solo dentro de una ventana abierta; consulta en el hub la [ventana de servicio al cliente](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird rechaza `http`; WhatsApp mismo lo obtendría.** Consulta en el hub [enviar medios por URL](/docs/guides/whatsapp/message-types#sending-media-by-url) para la comprobación completa de forma. - **Una obtención rechazada aun así se cobra, y este es el tipo de medio con más probabilidad de encontrarlo.** Con 100 MB, un documento es lo más grande que puedes enviar, y Bird no comprueba nada sobre los bytes reales al aceptar. Consulta en el hub [cuando un medio falla](/docs/guides/whatsapp/message-types#when-media-fails) para `media_rejected` y el hecho del cobro en caso de fallo. El texto de rechazo propio de documento desde WhatsApp no se ha medido de forma independiente como el de imagen, así que trata la correspondencia como inferida por simetría en vez de confirmada por causa. - **Omitir `filename` no significa que el destinatario no vea ningún nombre.** WhatsApp deriva uno a partir de la ruta de la URL, que puede ser un hash opaco o un slug en lugar de algo legible. Establece `filename` de forma explícita para controlar lo que realmente se muestra. - **El tope de 100 caracteres de `filename` es una decisión propia de Bird, no un límite de WhatsApp.** WhatsApp no documenta ningún límite de longitud de nombre de archivo. - **WhatsApp almacena en caché una URL obtenida durante unos 10 minutos.** Reenviar la misma URL dentro de esa ventana sirve de nuevo la primera obtención; varía la URL para forzar una nueva. ## Próximos pasos - [Mensajes de servicio de WhatsApp](/docs/guides/whatsapp/message-types): la ventana de servicio al cliente y el modelo que comparten todos los mensajes de servicio - [Imágenes](/docs/guides/whatsapp/message-types/images): para una foto o gráfico en lugar de un archivo - [Plantillas](/docs/guides/whatsapp/templates): para mensajes que puedes enviar una vez cerrada la ventana - [Enviar mensajes de WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la estructura de la solicitud, el modelo `202` y reintentos seguros ## 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)