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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
image={"url": "https://cdn.example.com/receipt.png"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Image: &bird.WhatsAppImageSend{Url: "https://cdn.example.com/receipt.png"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$image = (new WhatsAppMessageSendRequestImage())
->setUrl('https://cdn.example.com/receipt.png');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
image: $image,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--image https://cdn.example.com/receipt.png \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipt.png"
},
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipt.png"
}
}'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
| Campo | Límite | Validado por |
|---|---|---|
| Tamaño de archivo | 5 MB | Solo WhatsApp, al descargar (async) |
| Tipo de archivo | JPEG o PNG | Solo WhatsApp, al descargar (async) |
| caption | hasta 1024 caracteres | Bird, al aceptar (422) |
| url | absoluta, https, tiene host, sin espacios en crudo | Bird, 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
- Mensajes de servicio de WhatsApp: la ventana de servicio al cliente y el modelo que comparten todos los mensajes de servicio
- Video: la misma forma para un clip de video
- Documentos: para un PDF, una hoja de cálculo u otro archivo
- Enviar mensajes de WhatsApp: el sobre de la solicitud, el modelo 202 y reintentos seguros
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación