Saltar al contenido principal
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 el tope de tamaño de visión que le corresponde (no el de la tabla de abajo, que es el de subida). 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

Formato de video: video/mp4 y video/3gpp se aceptan solo con video H.264 y audio AAC (una sola pista de audio o ninguna). confirm lee el códec del archivo y rechaza cualquier otro —por ejemplo HEVC/H.265— con 400 VIDEO_CODEC_UNSUPPORTED, borrando el archivo. Convierte el video a H.264 antes de subirlo.
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 transcribible automáticamente, o por encima del tope de tamaño que le corresponde), 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
Qué tipos se transcriben solos puede ampliarse por etapas. La señal autoritativa por archivo es requires_transcription en la respuesta de /files/confirm, que te evita seguir esas etapas. Los topes detrás de esa señal son de visión, distintos de los límites de subida. .doc, .ppt y .pptx no se transcriben solos a ningún tamaño.Tres consecuencias prácticas:
  • requires_transcription responde al momento del confirm. El gate que manda es el del envío, así que un archivo confirmado con false puede volver a exigir transcription si la disponibilidad cambia entre el confirm y el envío. Ante la duda, mándala.
  • Mandar transcription junto a un file_uuid nunca es un error, aunque el archivo no la necesitara: gana sobre la transcripción automática. Sin file_uuid el body se rechaza entero con INVALID_REQUEST (400), igual que si transcription viene vacía o con puros espacios. En cambio, un texto que solo queda vacío al quitarle los caracteres de control pasa el schema: el body se acepta con 202 y es esa acción la que falla con INVALID_REQUEST durante la ejecución en background.
  • El tope de tamaño depende del tipo de archivo: no es un único número para todos.