Acompanhamento

Aprove o que o agente fez, trate os casos que ele abriu e acompanhe como ele está evoluindo.

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

CampoTipo e limitesUso
expected_revisioninteiroRevisão do caso.
statusopen | waiting | resolved | closedOpcional.
assigned_user_idUUID ou nullResponsável da equipe.
message1–10.000Nota no caso.
resume_agentbooleanDevolve 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

CampoTipo e limitesUso
enabledbooleanLiga os avisos. Exige consent_confirmed.
contact_id · template_idUUID ou nullDestinatário e template (veja options).
variable_map{"body:1": campo}Chaves body:N, header:N ou button:N; valores abaixo.
consent_confirmedbooleanConfirma que o destinatário autorizou receber.
expected_revisioninteiro ≥ 0Revisã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:

adjustmentEfeito
sem_travessao_longoSem 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.

StatusCódigoQuando
403forbiddenDecisão com chave que não foi criada por um Administrador.
404not_foundExecução, caso ou alerta fora do Cliente (em execuções, confira também agent_id).
409revision_conflictRevisão do caso, alerta, proposta ou configuração desatualizada.
409case_not_open · case_not_waiting · case_staleTransição de caso inválida para o estado atual.
409dispatch_busyEnvio em andamento ou incerto.
409draft_exists · base_version_changedAplicar instrução com rascunho aberto ou com o agente publicado depois do atendimento.
422invalidCorpo fora do contrato, inclusive confirm_send ausente.
422prompt_limitAplicar instrução levaria as instruções do agente além de 20.000 caracteres.
429rate_limitedConsultas internas de caso acima do limite.

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