Authorization: Bearer {BearerToken}. Os endereços seguem a URL base da API: https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/....
Rotas
Ids do caminho:
Erros comuns a todas as rotas
Nas recusas de validação,
ERR_INVALID_FIELD vem com field (ou fields) apontando o caminho do campo recusado, por exemplo temperature, externalTools[0].url ou actions[2].tagId.
Listar agentes
data vem uma lista de { id, name, isActive, description, kbOnly }.
A configuração completa de cada agente vem em Consultar agente.
Listar recursos do motor de agentes
data vem { engineFeatures: [...] }. Exemplos de recursos: actionsV5, routingV5, booking, scheduleMessage, kbJsonMd, agentHandoff, agentConsult, kbOnly, kbShared, replyDelay, mcp, inactivity e qualifyPass.
O que depende de um recurso fora da lista é ignorado ou não roda. Exemplos:
- Destino do tipo
ai_agentsem o recursoagentHandoff. qualifyPassEnabledsem o recursoqualifyPass.- Documento
.jsonou.mdsem o recursokbJsonMd.
Consultar agente
data vêm id, name, description, isActive, kbOnly, usePlatformAi, hasApiKey, baseUrl, model, systemPrompt, exitKeyword, temperature, maxHistoryMessages, kbEnabled, kbTopK, semanticEnabled, routingEnabled, routingTargets, autoSummaryEnabled, fallbackQueueId, transferMessage, externalTools, actions, actionMessage, memoryEnabled, memoryFields, closeRules, nativeTools, timezone, consultAgents, sharedKbAgents, replyDelayMin, replyDelayMax, mcpTools, inactivityConfig, qualifyPassEnabled, createdAt e updatedAt.
As
key dos itens (destinos, ferramentas e cards) são as que você reenvia em Editar agente. Um agente montado na tela sai aqui no mesmo formato descrito em Criar agente.
Criar agente
Obrigatórios
name.- A conexão com o modelo, que é uma destas:
apiKey: chave do provedor (OpenAI ou o compatível dobaseUrl);usePlatformAi: true: IA da plataforma, cobrada nos créditos de IA da empresa. Não mandeapiKeyjunto.
null valem como campo ausente. Sem apiKey e sem usePlatformAi: true, a rota responde 400 ERR_MISSING_FIELDS. Sem model, vale gpt-4o-mini; com a IA da plataforma, o modelo precisa estar no catálogo dela (senão, 422).
Campos do body
Só estes campos são aceitos; outra chave é ignorada.Validação
- Limites são recusados, nunca cortados nem ajustados: texto acima do tamanho, lista acima da quantidade e número fora da faixa (
temperature,maxHistoryMessages,kbTopK,replyDelayMinereplyDelayMax) respondem 400ERR_INVALID_FIELD, comfieldno caminho (ex.:temperature,externalTools[0].url). - Lista com mais de 50 itens é recusada logo de cara, antes de conferir os itens.
- Booleanos aceitam só
true,false,"true"ou"false"(outro valor responde 400ERR_INVALID_FIELDcomfield). A regra vale também dentro dos objetos e listas:closeRules.grace.enabled,nativeTools.booking.enabled,nativeTools.scheduleMessage.enabled,inactivityConfig.enabled,inactivityConfig.warning.enabled,externalTools[].params[].requiredeexternalTools[].secretClear.
Listas
Exemplo de um destino que transfere para uma fila:
Objetos
O nome dos motivos e dos tipos de evento vem do cadastro.
Keys dos itens
- Item sem
keyganha uma gerada (api_+ 8 caracteres), devolvida na resposta. keyprópria: só letras, números,_e-, até 40 caracteres.- Item que a tela descartaria (sem label, description ou nome, tipo inválido, key repetida) responde 400
ERR_INVALID_FIELDcomfield(ex.:routingTargets[1]).
Ids conferidos na empresa
Os ids (filas, usuários, fluxos, agentes, etiquetas, raias, funis, etapas, motivos, página e tipos de evento da agenda, servidores MCP) são conferidos na empresa do token: inexistente ou de outra empresa responde 400ERR_INVALID_FIELD, com field no caminho (ex.: actions[2].tagId). O stageId tem de ser do pipelineId do card, e os eventTypes, da bookingPageId.
baseUrl
httpouhttps, sem usuário e senha no endereço (usuario:senha@hostresponde 400ERR_INVALID_FIELDcomfieldbaseUrl).- Endereço de metadados de nuvem é recusado (400
ERR_INVALID_FIELD; conferência de melhor esforço ao salvar). - Com a IA da plataforma, o
baseUrlé ignorado.
Depois de criar
- O agente criado só responde depois de ligado a um canal (menu Canais) ou a um nó de fluxo no painel. Veja Ativar e Vincular um Agente.
- Repetir o pedido cria outro agente.
Resposta
201, com o agente completo dentro dedata, no formato de Consultar agente (sem a chave do provedor).
Erros
Editar agente
Como limpar um campo
nullou""limpam o campo: texto, número (comofallbackQueueId,replyDelayMinereplyDelayMax) e objeto (comocloseRules,nativeToolseinactivityConfig).[]limpa a lista.- Lista enviada substitui a lista inteira: para mudar um item, reenvie a lista completa com as
keydevolvidas por Consultar agente.
O que não se limpa
Conexão com o modelo
usePlatformAi: truepassa o agente para a IA da plataforma (semapiKeyjunto).falsenum agente da plataforma exigeapiKey.- Trocar o
baseUrlpara outro endereço (não vazio) num agente com chave própria exige reenviar aapiKeyno mesmo pedido, senão a rota responde 400ERR_MISSING_FIELDScomfields["apiKey"]: a chave salva nunca vai para um endereço novo. - Com a IA da plataforma, mandar
modelconfere o catálogo (422). - O
baseUrlsó é conferido quando muda.
Outras regras
- Ids conferidos na empresa: só os novos. Os que já estão salvos no agente passam, mesmo que a fila ou o agente referenciado tenha sido excluído.
- Ferramenta externa: reenvie a mesma
keye a mesmaurlcomsecretvazio para manter o segredo salvo, ou mandesecretClear: trueno item para apagar o segredo salvo. - Uma
keynova faz anotações e avisos à equipe já feitos nos atendimentos em curso poderem sair de novo. - A troca de chave vale também para os atendimentos em que o agente está respondendo, e outros processos do servidor podem usar a versão anterior por até 60 segundos.
Resposta
Dentro dedata, o agente completo, no formato de Consultar agente.
Erros
Duplicar agente
Regras:
- A cópia não herda o vínculo com canais nem com nós de fluxo.
- Se a passada de qualificação (
qualifyPassEnabled) está desligada no original, continua desligada na cópia. - Agente que usa a IA da plataforma: a cópia passa antes pela trava dos créditos de IA da empresa.
- Repetir o pedido cria outra cópia.
{ id, name, isActive, description, kbOnly } dentro de data. A configuração completa vem em Consultar agente.
Ver onde o agente é usado
kbOnly).
Dentro de data vem { sharedKbBy, transferFrom, consultedBy, channels }, cada um uma lista de { id, name }.
Os fluxos (nó Agente de IA e Fora do horário) não entram nesta lista: confira no painel.
Excluir agente
{}.
O que acontece:
- O agente é desligado dos canais.
- Os atendimentos abertos e pendentes em que ele está respondendo são soltos.
- A base de conhecimento dele é apagada (artigos, fontes e arquivos).
- Não são limpas as referências em outros agentes (destinos, consulta e base compartilhada) nem nos fluxos: ali o atendimento cai na fila de reserva ou o passo fica indisponível.
{ deleted: true } dentro de data.
Base de conhecimento
A base de conhecimento de um agente tem duas partes, cada uma com as suas rotas:
Regras das importações:
- Documento e link: limites de 20 fontes por agente, 400 trechos por fonte e 2.000 trechos por agente. Acima deles, a rota responde 400
ERR_AI_AGENT_SOURCE_LIMIT. - FAQ: até 400 perguntas por envio, dentro do limite de fontes do agente.
- Uma importação de documento ou link por vez em cada processo do servidor. Ocupado responde 429
ERR_AI_AGENT_SOURCE_BUSY: tente de novo em alguns segundos. - Com a busca semântica do agente ligada (
semanticEnabled), os artigos e os trechos de documento e de FAQ são vetorizados, com custo no provedor do agente ou nos créditos de IA.
Listar artigos
data vem uma lista de { id, title, content, isActive, createdAt, updatedAt }.
Criar artigo
Regras:
- Texto vazio vale como campo ausente:
contentausente, vazio ounullresponde 400ERR_MISSING_FIELDS. - Com a busca semântica do agente ligada, o artigo é vetorizado em segundo plano.
{ id, title, content, isActive, createdAt, updatedAt } dentro de data.
Editar artigo
A resposta traz o artigo
{ id, title, content, isActive, createdAt, updatedAt } dentro de data.
Excluir artigo
{}) e a resposta traz { deleted: true } dentro de data.
Listar fontes
data vem uma lista de { id, type, name, url, status, errorMessage, syncEnabled, chunkCount, lastSyncAt, createdAt }. O id é o sourceId de Sincronizar fonte e Excluir fonte.
Importar documento
multipart/form-data), não JSON, com o arquivo no campo media:
A resposta só sai quando o documento termina de ser lido e dividido em trechos. Pode levar minutos em arquivo grande: não corte a conexão antes.
data, no mesmo formato de Listar fontes.
Importar link
Este envio segue os limites e a regra de uma importação por vez de Base de conhecimento. Também responde 201, com a fonte dentro de
data, no formato de Listar fontes.
Importar FAQ
A resposta é 201, com a fonte dentro de
data, no formato de Listar fontes.
Sincronizar fonte
{}) e a resposta só sai quando a sincronização termina.
A resposta traz a fonte dentro de
data, no formato de Listar fontes.
Excluir fonte
{}) e a resposta traz { deleted: true } dentro de data.

