Sign inGet started

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:
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);
La forma completa añade caption y filename:
Ejemplo de código
{
  "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

CampoLímiteAplicado por
Tamaño de archivo100 MBSolo WhatsApp, al obtener el archivo (async)
Tipo de archivoPDF, Word, Excel, PowerPoint o texto plano se muestran de forma fiable en el cliente de WhatsApp; otros tipos se transmiten pero no están soportadosSolo WhatsApp, al obtener el archivo (async)
captionhasta 1024 caracteresBird, al aceptar (422)
filenamede 1 a 100 caracteresBird, al aceptar (422); este tope es propio de Bird, ya que WhatsApp no documenta ningún límite de nombre de archivo
urlabsoluta, https, con host, sin espacios en crudoBird, 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 y cuando un medio falla.

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 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.
  • Bird rechaza http; WhatsApp mismo lo obtendría. Consulta en el hub enviar medios por 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 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