Execuções
Uma execução é um turno do agente (ou um teste). Status: running, waiting, completed, awaiting_approval, failed, unknown, superseded, rejected.
GET /ai/executions
Escopo agents:read
Query customer_id, agent_id e status opcionais, page, per_page.
GET /ai/executions/{id}
Escopo agents:read
Query customer_id e agent_id, ambos obrigatórios.
{
"id": "14141414-1414-4141-8141-141414141414",
"agent_id": "44444444-4444-4444-8444-444444444444",
"version_id": "55555555-5555-4555-8555-555555555555",
"source": "live",
"mode": "assisted",
"status": "awaiting_approval",
"provider": "openai",
"model": "MODELO_VALIDADO_NA_CREDENCIAL",
"reply": "O prazo para Manaus é de 7 dias úteis.",
"tool_trace": [
{
"step": 1,
"call_id": "call_1",
"name": "knowledge.search",
"arguments": {
"query": "prazo Manaus"
},
"output": "[...]",
"status": "completed",
"error_code": null
}
],
"usage": {
"input_tokens": 1830,
"output_tokens": 96,
"cache_read_tokens": 0,
"cache_write_tokens": 0,
"reasoning_tokens": 0
},
"measurement_status": "measured",
"finish_reason": "stop",
"error_code": null,
"created_at": "2026-09-25T13:00:00.000Z",
"completed_at": "2026-09-25T13:00:04.000Z",
"run_id": "15151515-1515-4151-8151-151515151515",
"conversation_id": "99999999-9999-4999-8999-999999999999",
"latency_ms": 4012,
"security": {
"summary": {
"hold": null,
"guard": {
"verdict": "pass",
"level": "none",
"layer": "heuristic",
"codes": []
},
"evaluation": {
"verdict": "pass",
"attempts": 1,
"codes": []
},
"disclosure_version": 1
},
"events": [],
"events_unavailable": false
}
}security é a trilha de proteção: resumo (hold, detector, avaliação e versão do aviso de IA) e events com estágio, veredito, códigos e o vínculo usado (provedor, modelo, origem), sem texto de mensagem nem chave. events_unavailable: true indica que a trilha não pôde ser lida, não que não houve verificação. Com operador, operator_execution traz a execução dele no mesmo formato.
POST /ai/executions/{id}/decision
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, agent_id, decision: "approve" | "reject"}. Decide uma execução em awaiting_approval no modo assistido. Aprovar executa as ações e envia a resposta; retorna a execução atualizada. Pela API, a chave precisa ter sido criada por um Administrador; no painel, qualquer membro da conta (Operador ou Administrador) aprova ou rejeita.
Casos
O agente abre um caso quando precisa de uma decisão da equipe. Status open, waiting, resolved, closed; revision numérica.
GET /ai/cases
Escopo agents:read
Query customer_id, page, per_page e filtros status, kind (agendamento, duvida, problema, financeiro, acesso, outro) e source (agent, guardrail, human, operator, followup).
GET /ai/cases/{id}
Escopo agents:read
Query customer_id. Caso com title, summary, blocker, assigned_user_id, conversation_id, contact_id e a última decisão humana.
PATCH /ai/cases/{id}
Escopo agents:write · chave criada por um Administrador
| Campo | Tipo e limites | Uso |
|---|---|---|
expected_revision | inteiro | Revisão do caso. |
status | open | waiting | resolved | closed | Opcional. |
assigned_user_id | UUID ou null | Responsável da equipe. |
message | 1–10.000 | Nota no caso. |
resume_agent | boolean | Devolve a conversa ao agente. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"expected_revision": 4,
"status": "resolved",
"message": "Coleta agendada para sexta.",
"resume_agent": true
}POST /ai/cases/{id}/reply
Escopo agents:write · chave criada por um Administrador
Registra a decisão da equipe. action: resolved ou need_lead_info retomam o agente para repassar a solução ou a pergunta ao contato (no modo assistido, o envio aguarda aprovação); escalate mantém o atendimento humano. body de 1 a 4.000 caracteres.
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"expected_revision": 3,
"operation_key": "66666666-6666-4666-8666-666666666666",
"action": "need_lead_info",
"body": "Peça o número do pedido e uma foto da etiqueta."
}Retorna {case_id, revision, status, service_stale, queued, queue_reason, run_id}. Registrar a decisão não confirma o envio: confira queued e queue_reason.
POST /ai/cases/{id}/chat
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, operation_key, question} (question de 3 a 1.000). Consulta interna sobre o caso, com a sua chave, sem ferramentas e sem envio ao contato. Retorna o turno com reply, status, persona (o agente do caso ou, se indisponível, o assistente neutro com o provedor padrão do Cliente) e consumo. Repita a mesma operation_key para consultar uma tentativa incerta.
GET /ai/cases/{id}/chat
Escopo agents:read
Query customer_id, page, per_page. Histórico da consulta interna.
GET /ai/cases/{id}/events
Escopo agents:read
Query customer_id, page, per_page. Linha do tempo do caso, da mais antiga para a mais nova, com kind, label e autor.
GET /ai/cases/{id}/messages
Escopo agents:read
Query customer_id, page, per_page. Mensagens trocadas no caso.
Alertas
GET /ai/alerts
Escopo agents:read
Query customer_id, page, per_page e filtros status (open, acknowledged, resolved), kind e severity (info, warning, critical). Cada alerta traz kind_label, guidance e links para o caso, a conversa ou o agente.
A IA parada por causa que o dono corrige abre credential_unavailable, credential_rejected ou credential_quota_exhausted (critical, um por credencial). Um turno automático que termina sem resposta passa a conversa para a equipe quando handoff_enabled permite (handoff); sem isso, abre ai_unanswered, um por conversa. token_budget_exhausted aparece quando o mesmo agente atinge token_budget duas vezes em 24 horas. Um alerta resolvido volta a abrir se a causa se repetir.
PATCH /ai/alerts/{id}
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, expected_revision, status} com revisão numérica e open, acknowledged ou resolved.
POST /ai/alerts/resolve
Escopo agents:write · chave criada por um Administrador
Resolve em lote só o que existia até created_before (ISO com fuso), com filtros opcionais {kind, severity, status: open|acknowledged}. Alertas criados depois ficam abertos. Retorna {resolved_count, remaining}.
Avisos no WhatsApp
Avisa uma pessoa da equipe, por template Utility aprovado, quando um caso é aberto. Salvar não envia mensagem.
GET /ai/notices
Escopo agents:read
Query customer_id. {enabled, contact_id, template_id, variable_map, revision, consent_confirmed_at, updated_at}.
PATCH /ai/notices
Escopo agents:write · chave criada por um Administrador
| Campo | Tipo e limites | Uso |
|---|---|---|
enabled | boolean | Liga os avisos. Exige consent_confirmed. |
contact_id · template_id | UUID ou null | Destinatário e template (veja options). |
variable_map | {"body:1": campo} | Chaves body:N, header:N ou button:N; valores abaixo. |
consent_confirmed | boolean | Confirma que o destinatário autorizou receber. |
expected_revision | inteiro ≥ 0 | Revisão atual. |
Campos: case_title (Título do caso), case_summary (Resumo do caso), case_url (Link do caso no BotoZap), contact_name (Nome do contato atendido), contact_phone (Telefone do contato), contact_name_and_phone (Nome e telefone do contato), agent_name (Nome do agente).
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"enabled": true,
"contact_id": "88888888-8888-4888-8888-888888888888",
"template_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
"variable_map": {
"body:1": "case_title",
"body:2": "case_url"
},
"consent_confirmed": true,
"expected_revision": 0
}GET /ai/notices/options
Escopo agents:read
Query customer_id. {contacts, templates, channels} elegíveis.
GET /ai/notices/diagnostics
Escopo agents:read
Query customer_id. Lista de verificações {id, status: ok|warning|error, message}. error impede o aviso de sair. warning pede atenção: avisos desligados, nenhum agente que abra casos ou a conta travada pela Meta há pouco, em que o aviso espera o prazo da trava e tenta de novo (e falha se a Meta continuar recusando).
GET /ai/notices/effect
Escopo agents:read
Query customer_id e days (1–90, padrão 30). Compara casos com e sem aviso: quantidade, respondidos e mediana de minutos.
GET /ai/notices/jobs
Escopo agents:read
Query customer_id, page, per_page. Envios com status (pending, claimed, sent, failed, unknown, cancelled), last_error, meta_error_code e destino mascarado.
Um envio sent vira failed com last_error meta_failed quando a Meta avisa depois, pelo status da mensagem, que não conseguiu entregá-lo. meta_error_code traz o código da Meta nessa falha e na recusa feita na hora (meta_rejected); nos outros casos é null.
Um envio pending com last_error foi adiado por uma recusa passageira: account_locked (a conta travada pela Meta há pouco) ou capacity_unavailable (a leitura do estado do número que falhou). Ele espera a hora de tentar de novo; depois de 5 tentativas, passa a failed com o mesmo motivo.
POST /ai/notices/jobs/{id}/retry
Escopo agents:write
Corpo {customer_id}. Recoloca um envio falho na fila; retorna {queued: true}. Envios com resultado incerto não são repetidos automaticamente.
POST /ai/notices/test
Escopo agents:write
Corpo {customer_id, operation_key, confirm_send: true}. Envia uma mensagem real ao destinatário configurado. Retorna {id} do envio.
Propostas de aprendizado
O aprendizado analisa execuções e propõe um item de instrução (playbook_bullet) ou uma memória (memory_entry). Nada é aplicado sem decisão. Só entram atendimentos da versão publicada do agente ou de versões criadas ao aplicar propostas. Publicar outra versão pelo editor descarta as propostas de instrução pendentes (rejected com decision_reason explicando) e as análises ainda na fila.
GET /ai/proposals
Escopo agents:read
Query customer_id, status (pending, applied, rejected), agent_id, page, per_page. Cada proposta traz content, reason, evidence e revision.
PATCH /ai/proposals/{id}
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, expected_revision, decision: "apply" | "reject", reason?}. Aplicar uma instrução acrescenta o trecho à versão publicada e publica uma versão nova; as outras propostas pendentes do agente continuam aplicáveis. É recusado se houver rascunho em edição (409 draft_exists) ou se o agente foi publicado pelo editor depois do atendimento (409 base_version_changed). Aplicar uma memória a aprova.
POST /ai/proposals/analyze
Escopo agents:write
Corpo {customer_id, agent_id, limit} (limit 1–100, padrão 20 execuções). Enfileira a análise das execuções da versão publicada ainda sem análise, incluindo as que falharam antes, e responde 202 com {queued}. Se a chave estiver sem saldo (provider_quota_exhausted), recusada, ausente ou o orçamento acabar, as análises ainda na fila terminam com o mesmo motivo, sem nova chamada ao provedor.
GET /ai/proposals/settings
Escopo agents:read
Query customer_id. {enabled, revision}.
PATCH /ai/proposals/settings
Escopo agents:write
Corpo {customer_id, enabled, expected_revision} com revisão numérica (0 antes da primeira gravação).
Métricas, promessas e evolução
GET /ai/operator-metrics
Escopo agents:read
Query customer_id, days (1–90, padrão 30) e agent_id opcional. Por agente: turnos, promessas, quem assumiu cada uma (agente, operador, pessoa), correções e ownership_rate.
GET /ai/promises
Escopo agents:read
Query customer_id, agent_id, status (pending, owned, unowned, dismissed) e limit (1–100, padrão 50). Promessas declaradas pelo agente no fechamento do turno (accountability.enabled). Somente leitura: correções são feitas no painel. Não confunda com os retornos avulsos.
GET /ai/evolution
Escopo agents:read
Query customer_id, days (7, 30 ou 90; padrão 30) e agent_id opcional. Retorna sources com learning, knowledge, skills, routing e crm, cada uma com status próprio (ok ou error). Uma fonte com erro não é zero.
Ajustes de estilo
Correções determinísticas aplicadas ao texto antes do envio. Lista fechada, desligada por padrão:
| adjustment | Efeito |
|---|---|
sem_travessao_longo | Sem travessão longo: Troca o travessão longo (—) por vírgula. No início ou no fim de uma linha ele é removido, sem deixar vírgula solta nem pontuação dupla. Quebras de linha são preservadas. |
GET /ai/style-adjustments
Escopo agents:read
Query customer_id. {adjustments: [{adjustment, enabled, revision, updated_at, updated_by, updated_by_api_key}]}.
PUT /ai/style-adjustments
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, adjustment, enabled, expected_revision}, com revisão string ("0" para um ajuste nunca gravado).
Controle da conversa
POST /conversations/{id}/agent-control
Escopo agents:write
Corpo {"action": "pause"} ou {"action": "resume"}, sem customer_id. Pausa ou devolve a conversa ao agente. Retorna {conversation_id, paused}. ID malformado ou de outra Conta: 404 not_found. Em canal atendido por roteador, o controle vale para o agente que o roteador escolheu para a conversa (ou o fallback, antes de haver roteamento); conversa sem agente responsável não muda nada.
Para listar as conversas pausadas esperando um humano, use GET /conversations?agent_paused=true (escopo conversations:read, em Conversas e atribuições). Cada item traz agent_paused_at com o instante da pausa, ou null se o agente não está pausado.
Envios do agente com resultado incerto são conciliados no painel. Pela API, a conciliação existe para efeitos de follow-up e templates de retorno avulso, em Follow-ups e retornos.
| Status | Código | Quando |
|---|---|---|
| 403 | forbidden | Decisão com chave que não foi criada por um Administrador. |
| 404 | not_found | Execução, caso ou alerta fora do Cliente (em execuções, confira também agent_id). |
| 409 | revision_conflict | Revisão do caso, alerta, proposta ou configuração desatualizada. |
| 409 | case_not_open · case_not_waiting · case_stale | Transição de caso inválida para o estado atual. |
| 409 | dispatch_busy | Envio em andamento ou incerto. |
| 409 | draft_exists · base_version_changed | Aplicar instrução com rascunho aberto ou com o agente publicado depois do atendimento. |
| 422 | invalid | Corpo fora do contrato, inclusive confirm_send ausente. |
| 422 | prompt_limit | Aplicar instrução levaria as instruções do agente além de 20.000 caracteres. |
| 429 | rate_limited | Consultas internas de caso acima do limite. |
Visão geral do Agente de IA · Próxima: Propostas comerciais
