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.
| Campo | Tipo e limites | Uso |
|---|---|---|
kind | "file" | Arquivo do agente. |
file_name | 1–200, extensão .jpg, .jpeg, .png, .mp4, .mov ou .pdf | A extensão define o tipo. |
byte_size | inteiro, até 25 MB | Tamanho exato. |
sha256 | 64 hex minúsculos | Hash dos bytes. |
name | 1–80, obrigatório | Nome que a equipe e o agente veem. |
description | 1–500, obrigatório | Quando o agente deve mandar este arquivo. |
caption | opcional, até 1.024 caracteres e 1.000 bytes | Vai 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.
| Campo | Tipo e limites | Uso |
|---|---|---|
customer_id | uuid | Cliente do arquivo. |
expected_revision | string | A revisão que você leu; outra dá 409 revision_conflict. |
name, description, caption | opcionais | As mesmas regras do upload. |
active | boolean, opcional | false 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.
| Status | Código | Quando |
|---|---|---|
| 409 | in_use | O arquivo está numa versão publicada de agente: arquivar ou apagar é recusado. Tire o arquivo da versão e publique. |
| 409 | revision_conflict | O arquivo mudou depois da sua leitura. |
| 422 | file_quota_exceeded | A biblioteca do Cliente está cheia (100 arquivos ou 1 GB). |
| 422 | file_type_mismatch | O conteúdo não é o que a extensão diz. |
| 422 | video_unreadable | O 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"
}
}| Status | Código | Quando |
|---|---|---|
| 404 | file_not_found | O id não é de um arquivo ativo da biblioteca desta Conta (inexistente, de outra Conta ou arquivado). |
| 422 | file_not_ready | O arquivo ainda está convertendo ou não foi convertido. |
| 422 | file_type_mismatch | O type do envio não é o do arquivo. |
| 503 | storage_unavailable | O armazenamento não respondeu ao assinar o link. Repita em instantes. |
Visão geral do Agente de IA · Próxima: Roteadores
