Recibir imágenes de WhatsApp
Una foto o gráfico que un contacto envía llega como un mensaje entrante con image: una referencia al archivo que Bird almacenó para ti, más el pie de foto que hayan escrito debajo.
Qué contiene una imagen entrante
Ejemplo de código
{
"id": "wam_01kya19eknftrs2s6p82asmvnh",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"image": {
"id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
"mime_type": "image/jpeg",
"caption": "Is this the right part?"
},
"created_at": "2026-08-25T09:04:11Z"
}| Campo | Qué contiene |
|---|---|
| id | El archivo almacenado, para pasar como media_id al descargar los bytes |
| url | Una URL Bird, que se descarga con tu clave API |
| mime_type | El tipo de medio que WhatsApp reportó para el archivo, por ejemplo image/jpeg |
| caption | El texto que el contacto escribió bajo la imagen; ausente si no envió ninguno |
id y mime_type aparecen solo en una imagen entrante: Bird obtiene ambos al descargar el archivo, y nunca almacenó el que tú enviaste. Una imagen saliente se lee de vuelta con el url que proporcionaste y sin id.
Trata mime_type como el reporte de WhatsApp en lugar de una garantía, y decide con base en él en vez de en la extensión de archivo en url, que no lleva ninguna.
Descargar los bytes
url y id apuntan al mismo archivo almacenado: pasa el ID del mensaje y el id del medio al método de media del canal, en cualquier SDK, el CLI, o cURL. La guía de descarga de medios entrantes incluye esa llamada en todos los lenguajes, junto con las reglas de redirección y encabezados que sigue.
El mensaje y su medio expiran juntos, 30 días después de que llega el mensaje; la guía de descarga de medios entrantes define esa ventana y lo que las lecturas devuelven una vez que pasa. Almacena cualquier imagen que necesites conservar más tiempo mientras el mensaje aún sea legible.
El payload del webhook
whatsapp.received lleva el brazo image en el envelope del evento, referencia de medio incluida:
Ejemplo de código
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:04:11.118Z",
"data": {
"whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"image": {
"id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
"mime_type": "image/jpeg",
"caption": "Is this the right part?"
},
"tags": null,
"metadata": null
}
}El webhook se dispara cuando llega el mensaje, que también es cuando comienza la ventana de retención, así que un endpoint que encola la descarga en lugar de hacerla en línea tiene toda la ventana para ponerse al día.
Aspectos a considerar
- El pie de foto pertenece al contacto. Llega como texto plano sin formato ni información de entidades, así que muéstralo como texto.
- Una imagen por mensaje. Un contacto que envía varias fotos produce varios mensajes entrantes, cada uno con su propio id y su propia referencia de medio. Agrúpalos por from y hora de llegada; ningún array los reúne.
Próximos pasos
- Cómo funciona la recepción: el envelope entrante, la descarga de medios y el webhook whatsapp.received
- Mensajes de imagen WhatsApp: el lado de envío del mismo brazo
- Recibir documentos: la misma forma de medio, con el nombre de archivo del remitente
- Eventos de WhatsApp: la lista completa de eventos, por API o webhooks
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