Skip to main content
Para enviar imágenes, video, audio o documentos, primero subes el archivo y obtienes un file_uuid, que luego pasas a una acción de envío.
1

Pide una URL de subida

Con { filename, mime_type }. Responde 201 con file_uuid, upload_url, upload_token, storage_path y expires_at.
2

Sube el binario

Sube el archivo a la upload_url que recibiste, antes de que expire (expires_at).
3

Confirma

Con { file_uuid }. Responde 200 con file_uuid, mime_type, size_bytes, requires_transcription, download_url y expires_at. A partir de aquí el file_uuid es enviable.
Ya no declaras size_bytes al pedir la URL: el server mide el tamaño real al confirmar. En la respuesta de confirm, requires_transcription anticipa si este file_uuid requerirá una transcripción al usarlo en un envío — porque el tipo de archivo no es transcribible automáticamente o supera los 20 MB. Es una pista para prepararla con anticipación.Valida el tamaño del archivo localmente antes de subirlo: el límite por tipo y la cuota de almacenamiento se aplican al confirmar, con el binario ya transferido. Un negocio con el storage deshabilitado (quota_bytes = 0) o ya sobre el tope se rechaza en request-upload con 413 antes de transferir.

​
Límites de tamaño

Uploads pendientes concurrentes: un negocio puede tener a lo sumo 100 uploads sin confirmar a la vez. Al superarlo, request-upload responde 429 TOO_MANY_PENDING_UPLOADS con Retry-After — confirma o deja expirar los pendientes antes de pedir más. El flujo normal (request → PUT → confirm) nunca lo toca; solo afecta a integraciones que piden muchos request-upload por adelantado sin confirmar.

​
Enviar el archivo

Una vez confirmado, pasa el file_uuid a una acción de envío — como media directa en send_message, o como header de una plantilla:
El header.type ∈ image | video | document lleva file_uuid (document acepta un filename opcional) y una transcription obligatoria cuando la visión no puede transcribir el archivo (el requires_transcription de arriba lo anticipa). En send_message modo media, el file_uuid va a nivel de acción con body como caption opcional (el audio no admite caption) y la misma regla de transcription.
Si el preflight rechaza el grupo, la respuesta es un 4xx síncrono y ninguna acción se ejecuta. Ver Errores.
La media subida es efímera. No es un almacén permanente: bajo presión de la cuota de almacenamiento, el sistema puede eliminar automáticamente los archivos por antigüedad de último uso (los que llevan más tiempo sin enviarse salen primero; reusar un file_uuid en cualquier conversación renueva su “último uso” y lo mantiene vivo para todas). Conserva tu propia copia si necesitas un registro durable. La API no ofrece una descarga estable por file_uuid; la única descarga es la download_url firmada que devuelve /files/confirm, válida por tiempo limitado. Reenviar un file_uuid ya eliminado responde FILE_NOT_FOUND.Reutilización entre conversaciones. Un mismo file_uuid puede enviarse a varias conversaciones sin volver a subirlo, pero el archivo es uno solo: si la limpieza por cuota lo elimina, se pierde en todas las conversaciones que lo referencian. Si necesitas independencia entre conversaciones, sube un archivo por conversación.

​
Ejemplo ejecutable

El flujo completo en tres llamadas. El file_uuid que confirma el paso 3 es el que después pasas a una acción de envío. 1 · Pide la URL de subida
2 · Sube el binario a la upload_url antes de que expire
3 · Confirma

​
Con transcripción obligatoria

Si el archivo no es auto-transcribible por la visión (tipo no soportado como .docx/.xlsx, o mayor a 20 MB), la respuesta de /confirm lo anticipa con requires_transcription: true:
Respuesta 200 (requiere transcripción)
En ese caso, al enviarlo debes incluir transcription — como media primaria en send_message o como template.header.transcription — o la acción falla con TRANSCRIPTION_REQUIRED / TEMPLATE_HEADER_TRANSCRIPTION_MISSING:
Enviar con transcripción