Multimedia: subir, enviar y administrar archivos

Formatos y límites de esta versión

JPEG (image/jpeg) y PNG (image/png): hasta 5 MiB. PDF (application/pdf): hasta 10 MiB. MP3 (audio/mpeg), OGG con Opus (audio/ogg) y MP4 (video/mp4): hasta 16 MiB. Un MiB equivale a 1.048.576 bytes. Estos son límites de WhatsAut; no representan todos los formatos/tamaños que puede admitir Meta.

Se comprueba el tipo declarado, el tamaño y la cabecera inicial del archivo. Meta valida el formato completo y los códecs; esta comprobación no es un antivirus ni una conversión de archivos. No se admiten documentos de Office, stickers, enlaces públicos ni encabezados multimedia de plantillas en este recorrido.

Subir un archivo

POST /api/runtime/v1/PHONE_NUMBER_ID/media con Authorization: Bearer de una clave media:write. Enviá los bytes originales del archivo y su Content-Type exacto; no multipart, JSON ni base64. WhatsAut construye internamente la petición multipart hacia Meta.

Respuesta: {"id":"MEDIA_ID"}. Guardá ese ID en tu integración para usarlo con /messages. No se guardan el contenido ni el nombre original en WhatsAut. La subida no envía un mensaje al cliente.

curl --request POST "https://whatsaut.com/api/runtime/v1/$PHONE_NUMBER_ID/media" \
  --header "Authorization: Bearer $WHATSAUT_KEY" \
  --header "Content-Type: image/png" \
  --data-binary @imagen.png

Consultar metadata

GET /api/runtime/v1/PHONE_NUMBER_ID/media/MEDIA_ID requiere media:read y no admite cuerpo ni query parameters. Devuelve sólo id, mime_type y file_size. La URL temporal de Meta no se devuelve al cliente.

WhatsAut fija phone_number_id a partir de la conexión y lo envía a Meta para comprobar pertenencia. Conocer un ID no permite acceder a archivos de otra conexión. La comprobación depende de Meta; no mantenemos un inventario local de archivos.

curl "https://whatsaut.com/api/runtime/v1/$PHONE_NUMBER_ID/media/$MEDIA_ID" \
  --header "Authorization: Bearer $WHATSAUT_KEY"

Descargar el contenido

GET /api/runtime/v1/PHONE_NUMBER_ID/media/MEDIA_ID/download requiere media:read. Devuelve los bytes con Content-Type, descarga como archivo adjunto y Cache-Control: no-store. Primero consulta metadata vigente y verifica la pertenencia al número.

Sólo se admite HTTPS en lookaside.fbsbx.com, ruta /whatsapp_business/attachments/, con direcciones públicas validadas y conexión fijada a una de ellas. No se siguen redirects ni se aceptan URLs del cliente. Si Meta devuelve otro host/ruta, la descarga se rechaza hasta revisar y habilitar ese contrato.

El contenido se verifica contra el tamaño reportado y el formato permitido. No se conserva en disco. Meta y tu integración tienen sus propias políticas de almacenamiento.

curl "https://whatsaut.com/api/runtime/v1/$PHONE_NUMBER_ID/media/$MEDIA_ID/download" \
  --header "Authorization: Bearer $WHATSAUT_KEY" \
  --output archivo.png

Eliminar un archivo de Meta

DELETE /api/runtime/v1/PHONE_NUMBER_ID/media/MEDIA_ID requiere media:write y no admite cuerpo. El phone_number_id se fija internamente para proteger archivos de otros números. Sólo se confirma con {"success":true} si Meta lo confirma.

Eliminá únicamente archivos que ya no necesites. Esta operación no borra mensajes ya recibidos por clientes ni constituye un mecanismo para retirarlos.

curl --request DELETE "https://whatsaut.com/api/runtime/v1/$PHONE_NUMBER_ID/media/$MEDIA_ID" \
  --header "Authorization: Bearer $WHATSAUT_KEY"

Permisos, frecuencia y errores

Las operaciones /media comparten diez intentos por conexión y minuto, entre todas sus claves. Los intentos autenticados inválidos también consumen presupuesto. Hay como máximo dos transferencias simultáneas por proceso y 30 segundos para leer una subida. Las solicitudes ya autorizadas pueden finalizar aunque se revoque la clave.

No hay reintentos automáticos. media_outcome_unknown (502/504) significa que no se conoce el resultado: no repitas a ciegas una subida o eliminación. Un 200 de envío multimedia tampoco confirma entrega al cliente.

Errores: unsupported_media_type (415), media_type_mismatch o invalid_media_id (400), media_too_large (413), media_rejected o media_metadata_invalid o media_download_failed (502), upload_timeout (408), upload_busy o rate_limited (429, Retry-After: 60). Conservá el request ID para diagnóstico y evitá registrar claves, URLs temporales y contenido.