Sign inGet started

Mensajes de imagen de WhatsApp

Un mensaje de imagen lleva una URL pública que WhatsApp descarga en el momento del envío, con un pie de imagen opcional debajo.

Enviar una imagen

Establece image.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);
La forma completa añade un caption opcional:
Ejemplo de código
{
  "to": "+16505551234",
  "from": "+13124495648",
  "image": {
    "url": "https://cdn.example.com/receipts/a1b2c3.png",
    "caption": "Your receipt for order A1B2C3"
  }
}
image no tiene el campo filename. from es obligatorio en todo mensaje de servicio: un número que pertenece a tu espacio de trabajo, no uno gestionado por Bird.

Límites

CampoLímiteValidado por
Tamaño de archivo5 MBSolo WhatsApp, al descargar (async)
Tipo de archivoJPEG o PNGSolo WhatsApp, al descargar (async)
captionhasta 1024 caracteresBird, al aceptar (422)
urlabsoluta, https, tiene host, sin espacios en crudoBird, al aceptar (422)
Bird comprueba la forma de la URL y la longitud del pie de imagen antes de poner nada en cola. No comprueba el tamaño ni el tipo real del archivo; solo la descarga propia de WhatsApp en el momento del envío puede hacerlo. Consulta en el hub enviar medios por URL para saber qué cubre esa comprobación de forma, y cuando un medio falla para saber qué ocurre cuando la descarga de WhatsApp rechaza el archivo.

Leer una imagen entrante

Una imagen entrante lleva el mismo objeto image, más un id y mime_type que Bird obtuvo al descargar el archivo. Ambos están ausentes en una lectura de un mensaje saliente, ya que Bird nunca descargó el archivo que envió. Consulta Recibir imágenes de WhatsApp para ver 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 tiene que estar abierta. Las imágenes son mensajes de servicio, solo se pueden entregar dentro de una ventana abierta; consulta en el hub la ventana de servicio al cliente.
  • Bird rechaza http; WhatsApp sí la descargaría. Esa distinción, y el resto de la comprobación de forma de la URL, están en el hub en enviar medios por URL.
  • Un archivo demasiado grande, un tipo MIME incorrecto o una URL inalcanzable fallan de la misma forma, y después del cobro. Consulta en el hub cuando un medio falla para ver media_rejected y el dato del cobro en caso de fallo.
  • WhatsApp almacena en caché una URL descargada durante unos 10 minutos. Reenviar la misma URL dentro de esa ventana sirve la primera descarga en lugar de descargar de nuevo; varía la URL (un parámetro de consulta, por ejemplo) para forzar una nueva.

Próximos pasos