Skip to main content
Para enviar imagens, vídeo, áudio ou documentos, primeiro você envia o arquivo e obtém um file_uuid, que depois passa a uma ação de envio.
1

Peça uma URL de upload

Com { filename, mime_type }. Responde 201 com file_uuid, upload_url, upload_token, storage_path e expires_at.
2

Envie o binário

Envie o arquivo para a upload_url que você recebeu, antes que expire (expires_at).
3

Confirme

Com { file_uuid }. Responde 200 com file_uuid, mime_type, size_bytes, requires_transcription, download_url e expires_at. A partir daqui o file_uuid é enviável.
Você não declara mais size_bytes ao pedir a URL: o server mede o tamanho real ao confirmar. Na resposta de confirm, requires_transcription sinaliza se este file_uuid exigirá uma transcrição ao usá-lo em um envio — porque o tipo de arquivo não é transcritível automaticamente ou passa de 20 MB. É uma dica para prepará-la com antecedência.Valide o tamanho do arquivo localmente antes de enviá-lo: o limite por tipo e a cota de armazenamento são aplicados ao confirmar, com o binário já transferido. Um negócio com o storage desabilitado (quota_bytes = 0) ou já acima do teto é rejeitado em request-upload com 413 antes da transferência.

​
Limites de tamanho

Uploads pendentes concorrentes: um negócio pode ter no máximo 100 uploads sem confirmar por vez. Ao ultrapassar, request-upload responde 429 TOO_MANY_PENDING_UPLOADS com Retry-After — confirme ou deixe expirar os pendentes antes de pedir mais. O fluxo normal (request → PUT → confirm) nunca o atinge; só afeta integrações que pedem muitos request-upload antecipadamente sem confirmar.

​
Enviar o arquivo

Uma vez confirmado, passe o file_uuid a uma ação de envio — como mídia direta em send_message, ou como header de um template:
O header.type ∈ image | video | document leva file_uuid (document aceita um filename opcional) e uma transcription obrigatória quando a visão não pode transcrever o arquivo (o requires_transcription acima antecipa isso). Em send_message no modo mídia, o file_uuid vai no nível da ação com body como legenda opcional (o áudio não admite legenda) e a mesma regra de transcription.
Se o preflight rejeitar o grupo, a resposta é um 4xx síncrono e nenhuma ação é executada. Ver Erros.
A mídia enviada é efêmera. Não é um armazenamento permanente: sob pressão da cota de armazenamento, o sistema pode excluir automaticamente os arquivos por antiguidade do último uso (os que estão há mais tempo sem serem enviados saem primeiro; reutilizar um file_uuid em qualquer conversa renova seu “último uso” e o mantém vivo para todas). Guarde sua própria cópia se precisar de um registro durável. A API não oferece um download estável por file_uuid; o único download é a download_url assinada que /files/confirm retorna, válida por tempo limitado. Reenviar um file_uuid já excluído responde FILE_NOT_FOUND.Reutilização entre conversas. O mesmo file_uuid pode ser enviado a várias conversas sem reenviar o arquivo, mas o arquivo é único: se a limpeza por cota o excluir, ele é perdido em todas as conversas que o referenciam. Se precisar de independência entre conversas, envie um arquivo por conversa.

​
Exemplo executável

O fluxo completo em três chamadas. O file_uuid que o passo 3 confirma é o que você depois passa a uma ação de envio. 1 · Peça uma URL de upload
2 · Envie o binário para a upload_url antes que expire
3 · Confirme

​
Com transcrição obrigatória

Se o arquivo não for auto-transcrevível pela visão (tipo não suportado como .docx/.xlsx, ou maior que 20 MB), a resposta de /confirm antecipa isso com requires_transcription: true:
Resposta 200 (requer transcrição)
Nesse caso, ao enviá-lo você deve incluir transcription — como mídia primária em send_message ou como template.header.transcription — ou a ação falha com TRANSCRIPTION_REQUIRED / TEMPLATE_HEADER_TRANSCRIPTION_MISSING:
Enviar com transcrição