Arquivos do agente

Fotos, vídeos e PDFs da empresa que o agente pode mandar na conversa.

A biblioteca guarda os arquivos de cada Cliente, com um nome, a explicação de quando mandar (description, que o agente lê) e uma legenda opcional. O agente só manda os arquivos escolhidos na versão (file_ids, até 40) e só com a ferramenta conversations.attach_files em tool_ids; veja Agentes e versões. São até 3 arquivos por resposta, só com a janela de 24 horas aberta, e cada um sai como uma mensagem, antes do texto: no WhatsApp com a legenda junto; no Instagram a legenda vai como texto logo depois.

Formatos, limites e conversão

Foto JPG ou PNG, vídeo MP4 ou MOV e PDF, até 25 MB no envio e 100 arquivos (1 GB) por Cliente. O que já sai nos dois canais fica ready na hora: foto JPEG colorida ou PNG de 8 bits (RGB ou RGBA) até 5 MB, vídeo MP4 H.264 com áudio AAC até 16 MB e PDF até 25 MB. O resto fica processing e é convertido: vídeo do iPhone (HEVC/.mov) e MP4 grande viram MP4 H.264 de até 16 MB (vídeo de até 3 minutos); foto grande vira JPEG, ou PNG quando tem transparência, de até 5 MB. Se a conversão não der certo, o arquivo fica failed com o motivo em last_error (video_too_long, video_too_heavy, dimensions_too_large, conversion_too_large, video_unreadable, image_unreadable, source_missing ou attempts_exhausted, quando a conversão caiu três vezes); envie outra versão. Entre uma tentativa e outra, o arquivo segue processing e o last_error mostra a falha da última. A legenda tem até 1.024 caracteres e 1.000 bytes UTF-8, o limite do texto no Instagram.

Upload

O arquivo entra pelo upload direto, com kind: "file": o POST /ai/uploads devolve a URL assinada, os bytes vão com PUT direto para o armazenamento e o POST /ai/uploads/{id}/complete confere os bytes e devolve o arquivo.

CampoTipo e limitesUso
kind"file"Arquivo do agente.
file_name1–200, extensão .jpg, .jpeg, .png, .mp4, .mov ou .pdfA extensão define o tipo.
byte_sizeinteiro, até 25 MBTamanho exato.
sha25664 hex minúsculosHash dos bytes.
name1–80, obrigatórioNome que a equipe e o agente veem.
description1–500, obrigatórioQuando o agente deve mandar este arquivo.
captionopcional, até 1.024 caracteres e 1.000 bytesVai junto da foto ou do vídeo. Vazio ou null: sem legenda.
{
  "customer_id": "33333333-3333-4333-8333-333333333333",
  "kind": "file",
  "file_name": "anel-solitario.jpg",
  "mime_type": "image/jpeg",
  "byte_size": 1843200,
  "sha256": "4f8b42c22dd3729b519ba6f68d2da7cc5b2d606d05daed5ad5128cc03e6c6358",
  "name": "Anel solitário ouro 18k",
  "description": "Quando perguntarem pelo anel solitário, pelo preço ou pelo tamanho dele.",
  "caption": "Anel solitário em ouro 18k"
}

Biblioteca

GET /ai/files

Escopo agents:read

Query customer_id. Os arquivos do Cliente, do mais novo ao mais antigo, com status e last_error.

GET /ai/files/{id}

Escopo agents:read

Query customer_id. O arquivo, as versões de agente que o usam (usages) e um link curto para ver o arquivo (preview_url, que vence em preview_expires_at, 10 minutos; null sem armazenamento). A resposta vem com Cache-Control: private, no-store: não guarde nem registre o link.

{
  "id": "8f6c1d2e-3b4a-4c5d-9e6f-7a8b9c0d1e2f",
  "customer_id": "33333333-3333-4333-8333-333333333333",
  "name": "Anel solitário ouro 18k",
  "description": "Quando perguntarem pelo anel solitário, pelo preço ou pelo tamanho dele.",
  "caption": "Anel solitário em ouro 18k",
  "media_type": "image",
  "mime_type": "image/jpeg",
  "file_name": "anel-solitario.jpg",
  "byte_size": 1843200,
  "status": "ready",
  "last_error": null,
  "active": true,
  "revision": "1",
  "created_at": "2026-11-11T12:00:00Z",
  "updated_at": "2026-11-11T12:00:00Z",
  "usages": [
    {
      "agent_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Mari",
      "version_number": 4,
      "published": true
    }
  ],
  "preview_url": "https://…",
  "preview_expires_at": "2026-11-11T12:10:00Z"
}

PATCH /ai/files/{id}

Escopo agents:write

A mudança vale na hora: o nome, o “quando enviar” e a legenda são lidos a cada resposta, então os agentes publicados que usam o arquivo já mandam a versão nova, sem publicar de novo.

CampoTipo e limitesUso
customer_iduuidCliente do arquivo.
expected_revisionstringA revisão que você leu; outra dá 409 revision_conflict.
name, description, captionopcionaisAs mesmas regras do upload.
activeboolean, opcionalfalse arquiva: o arquivo sai da escolha dos agentes.

DELETE /ai/files/{id}

Escopo agents:write

Corpo com customer_id e expected_revision. Apaga de vez; pelo OAuth, só Administrador. As mensagens que já mandaram o arquivo continuam mostrando a mídia.

StatusCódigoQuando
409in_useO arquivo está numa versão publicada de agente: arquivar ou apagar é recusado. Tire o arquivo da versão e publique.
409revision_conflictO arquivo mudou depois da sua leitura.
422file_quota_exceededA biblioteca do Cliente está cheia (100 arquivos ou 1 GB).
422file_type_mismatchO conteúdo não é o que a extensão diz.
422video_unreadableO vídeo não pôde ser lido.

Enviar pela API

Fora do agente, a sua integração manda um arquivo da biblioteca no POST /v1/messages: em image, video ou document, informe file_id no lugar do link. O arquivo sai por um link curto assinado do armazenamento, que o WhatsApp e o Instagram buscam no envio; o resto é igual à mídia por link (janela, cobrança, recibo). A legenda da biblioteca não entra sozinha: no WhatsApp, mande caption se quiser (o Instagram não aceita legenda). O PDF leva o nome do arquivo quando o corpo não traz filename. Vale qualquer arquivo ativo e ready da Conta da chave, com o type do media_type dele; a chave sandbox recebe 403 sandbox_forbidden, porque a biblioteca é de produção. A mensagem enviada aponta para o arquivo da biblioteca, sem cópia.

{
  "to": "+5531988887777",
  "type": "image",
  "image": {
    "file_id": "8f6c1d2e-3b4a-4c5d-9e6f-7a8b9c0d1e2f",
    "caption": "Anel solitário em ouro 18k"
  }
}
StatusCódigoQuando
404file_not_foundO id não é de um arquivo ativo da biblioteca desta Conta (inexistente, de outra Conta ou arquivado).
422file_not_readyO arquivo ainda está convertendo ou não foi convertido.
422file_type_mismatchO type do envio não é o do arquivo.
503storage_unavailableO armazenamento não respondeu ao assinar o link. Repita em instantes.

Visão geral do Agente de IA · Próxima: Roteadores