La biblioteca de Archivos permite cargar recursos desde el panel o desde tu servidor. Central configura la cantidad de archivos, el espacio total y el máximo por archivo en el plan o contrato particular.
Permisos y entorno
Usa una clave con files:read para consultar y descargar, y files:write para reservar, cargar, comprobar y eliminar. Un permiso de escritura no incluye lectura. Las claves pertenecen a un cliente y entorno; producción y pruebas conservan registros separados, pero comparten el cupo físico del contrato.
Las claves se utilizan en tu servidor. No las publiques en el navegador ni en el código de una página web.
Cargar un archivo
Primero reserva el archivo con POST /v1/files, Bearer e Idempotency-Key. Conserva esa clave para recuperar la misma reserva si pierdes la respuesta. Repetirla con datos distintos produce un conflicto.
{
"filename": "guia.pdf",
"size": 12540,
"content_type": "application/pdf",
"environment": "live"
}
size es el tamaño exacto en bytes. Puedes incluir sha256, con 64 caracteres hexadecimales en minúscula, para verificar el contenido. El límite de la plataforma es 100 MiB y el contrato puede establecer uno menor. La reserva vence a los 15 minutos.
Después envía los bytes a POST /v1/files/{id}/content con Bearer, Content-Type: application/octet-stream y Content-Length exacto. No uses JSON, multipart, compresión ni transferencia por fragmentos. La carga comprueba tamaño, firma del formato e integridad antes de publicar el archivo.
Se aceptan JPEG, PNG, GIF, WebP, MP4, 3GPP, MP3, Ogg, AAC, AMR y PDF cuando el detector reconoce su firma. La extensión y el tipo declarado por sí solos no acreditan el formato. Esta comprobación no es un análisis antivirus ni garantiza que cada canal acepte ese formato.
Consultar, descargar y eliminar
| Operación | Ruta |
|---|---|
| Listar y consultar el cupo | GET /v1/files?environment=live&page=1&pageSize=10 |
| Consultar un registro | GET /v1/files/{id} |
| Descargar con autenticación | GET /v1/files/{id}/content |
| Comprobar una carga incierta | POST /v1/files/{id}/reconcile |
| Eliminar | DELETE /v1/files/{id} |
El listado admite q, state (all, ready, pending, failed) y tamaños de página 10, 20, 30 o 50. La descarga verifica los bytes y entrega un adjunto privado con Cache-Control: private, no-store.
Si pierdes la respuesta de carga, consulta el mismo ID. Si está ready, ya puedes usarlo. uploading indica una carga en curso; uncertain conserva el espacio reservado hasta comprobar qué ocurrió. No crees otra copia automáticamente. Una comprobación sin evidencia suficiente mantiene ese estado y puede devolver 409.
La eliminación libera espacio cuando el almacenamiento confirma el borrado. Si queda deleting, la tarea de mantenimiento vuelve a intentarlo. El registro de auditoría se conserva, mientras se retiran nombre e integridad del archivo eliminado. Los archivos caducan según la retención vigente del cliente.
Puedes seleccionar estos archivos como muestras de plantillas de Meta directa. Twilio puede usar enlaces temporales de la biblioteca. Para enviar un archivo desde Mensajes, Campañas o la API con file_id, consulta adjuntos de WhatsApp.