Saltar para o conteúdo principal
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 do limite de tamanho de visão que lhe corresponde (não o da tabela abaixo, que é o de upload). É 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

Formato de vídeo: video/mp4 e video/3gpp são aceitos somente com vídeo H.264 e áudio AAC (uma única faixa de áudio ou nenhuma). O confirm lê o codec do arquivo e rejeita qualquer outro —por exemplo HEVC/H.265— com 400 VIDEO_CODEC_UNSUPPORTED, excluindo o arquivo. Converta o vídeo para H.264 antes de enviá-lo.
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 transcrevível automaticamente, ou acima do limite de tamanho que lhe corresponde), 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
Quais tipos são transcritos automaticamente pode ampliar-se por etapas. O sinal autoritativo por arquivo é requires_transcription na resposta de /files/confirm, que evita ter que acompanhar essas etapas. Os limites por trás desse sinal são de visão, distintos dos limites de upload. .doc, .ppt e .pptx não são transcritos automaticamente em nenhum tamanho.Três consequências práticas:
  • requires_transcription responde no momento do confirm. O gate que manda é o do envio, então um arquivo confirmado com false pode voltar a exigir transcription se a disponibilidade mudar entre o confirm e o envio. Na dúvida, envie-a.
  • Enviar transcription junto a um file_uuid nunca é erro, mesmo que o arquivo não precisasse: ganha sobre a transcrição automática. Sem file_uuid o body inteiro é rejeitado com INVALID_REQUEST (400), assim como uma transcription vazia ou só com espaços. Já um texto que só fica vazio ao remover os caracteres de controle passa pelo schema: o body é aceito com 202 e é essa ação que falha com INVALID_REQUEST durante a execução em background.
  • O limite de tamanho depende do tipo de arquivo: não é um número único para todos.