API de WhatsApp: formatos de archivo y límites de tamaño

¿Debo subir el archivo o enviar un enlace?

Meta recomienda subir el archivo y enviar su ID de medio. También puede enviar un enlace a un archivo alojado en un servidor público, pero las referencias de Meta para imágenes, vídeo y documentos indican que se prefiera el ID subido por su mejor rendimiento, y su guía sobre el rendimiento dice lo mismo para volúmenes altos.

Con el punto de conexión de Meta, una subida es un POST a /<PHONE_NUMBER_ID>/media con el archivo, su tipo MIME y messaging_product=whatsapp, y la respuesta es {"id": "<MEDIA_ID>"}. Los archivos subidos se cifran y se conservan 30 días, salvo que los elimine antes.

En el punto de conexión de WhatsApp de OmniChannels.ai, un mensaje multimedia lleva mediaUrl (una URL HTTPS pública) o mediaFile (un archivo que sube junto con la solicitud), con el pie de foto en content. Consulte la documentación de la API de WhatsApp. Pregunte a nuestro equipo cómo gestiona su cuenta el almacenamiento y la reutilización de archivos en envíos grandes.

¿Cuánto tiempo son válidos los ID de medio?

Meta documenta 30 días para un ID devuelto por una subida y 7 días para un ID recibido en un webhook entrante. La URL de descarga que se devuelve para un ID caduca a los 5 minutos.

Consecuencias prácticas:

• No guarde en caché un ID de medio durante meses. Conserve su archivo original y vuelva a subirlo cuando se rechace un ID.
• Descargue los archivos entrantes en cuanto llegue el evento y guarde su propia copia.
• No almacene nunca una URL de descarga obtenida; pida una nueva cuando la necesite.

¿Puedo añadir pies de foto a los mensajes multimedia?

Sí. Los mensajes de imagen, vídeo y documento admiten un pie de foto opcional de hasta 1.024 caracteres, según las referencias de mensajes de Meta. Los pies de foto son texto plano junto al archivo.

Los mensajes de audio y de sticker no tienen pie de foto en este modelo. Si necesita acompañar una nota de voz con palabras, envíe un mensaje de texto breve a su lado. Dentro de la ventana de atención al cliente los pies de foto son libres; fuera de ella, el archivo debe viajar dentro de una plantilla aprobada.

¿Cómo funcionan los archivos multimedia en las plantillas de mensaje?

Una plantilla puede llevar una imagen, un vídeo o un documento en el encabezado, y ese encabezado queda fijado al crear la plantilla. Al enviar una plantilla a aprobación, usted aporta un archivo de muestra, y puede indicar el archivo real al enviar.

En nuestra API, headerFormat puede ser IMAGE, VIDEO o DOCUMENT al crear la plantilla, headerFile lleva la muestra, y mediaUrl en el momento del envío sustituye el archivo del encabezado. Consulte la documentación de plantillas de Meta para conocer los requisitos de los archivos de muestra. Véanse categorías de plantillas y aprobación y ejemplos de plantillas.

¿Cómo descargo un archivo que envía un cliente?

Un archivo entrante llega mediante un webhook con un ID de medio; usted lo convierte en una URL y lo descarga con autorización.

1. Lea el ID de medio del evento del mensaje entrante.
2. Solicite la URL del archivo para ese ID. La respuesta de Meta incluye url, mime_type, sha256 y file_size.
3. Envíe un GET a esa URL con una cabecera Authorization: Bearer <token>. Sin el token, la solicitud falla.
4. Compruebe la cabecera Content-Type y el valor sha256, y después guarde el archivo.
5. Si recibe un 404, solicite una URL nueva y reintente; si sigue fallando, renueve el token de acceso.

El tamaño máximo de archivo entrante en la API Cloud es de 100 MB según Meta. Un archivo mayor activa un webhook con el código de error 131052; pida al cliente que envíe un archivo más pequeño o que lo comparta de otra forma. Analice cada archivo antes de abrirlo internamente. Véase la guía de webhooks y confirme con su ingeniero de incorporación cómo se entregan los archivos entrantes en su cuenta.

Ejemplo práctico: una clínica dental que envía informes

«Nile Smile Clinic» (sintética), en El Cairo, envía tarjetas de cita e informes de radiografías.

1. Las tarjetas de cita son imágenes PNG de 300 KB con un pie de foto de dos líneas. Muy por debajo de 5 MB.
2. Los informes de tratamiento son PDF de 2 a 8 MB, llamados report-2026-0381.pdf, enviados como documentos.
3. Un vídeo de 25 MB con un recorrido por la clínica es demasiado grande para un vídeo. El equipo lo recodifica como MP4 H.264/AAC de menos de 16 MB con faststart.
4. Los pacientes envían fotos de recetas. La bandeja de entrada descarga cada archivo de inmediato, porque el ID entrante caduca a los 7 días.
5. Un saludo de voz se exporta como OGG Opus mono, porque se rechazan las demás variantes de OGG.

¿Cuáles son los errores más comunes?

• Juzgar solo por el tamaño. Una imagen de 3 MB en el formato de color equivocado o un vídeo con el códec incorrecto falla igualmente.
• Desajuste de tipo MIME. Un .jpg servido como application/octet-stream es una causa clásica del error 131053.
• Enlazar a una URL lenta o privada, como un enlace firmado que ha caducado o una página tras un inicio de sesión.
• Confiar en un ID de medio antiguo. Los ID caducan a los 30 días.
• Ignorar la caducidad de los entrantes. Los archivos de los clientes deben guardarse en un plazo de 7 días.
• Un WebP animado como imagen. Se rechaza; use un sticker o un vídeo.
• Los límites cambian. Vuelva a consultar la referencia de Meta antes de fijar las validaciones en el código.

Cómo le ayuda OmniChannels.ai

OmniChannels.ai envía mensajes de WhatsApp de imagen, vídeo, audio, documento y sticker mediante una sola API, con un enlace público o un archivo subido y un pie de foto, y muestra los archivos multimedia y los adjuntos en la bandeja de entrada compartida. BroadNet es un Business Solution Provider oficial de Meta, por lo que las plantillas con encabezado de imagen, vídeo o documento pueden crearse y seguirse con su estado de aprobación. Lea la documentación de la API de WhatsApp y los errores y límites, o conozca el canal de WhatsApp.