APIs: conecte a IA aos seus sistemas

Sem APIs, o agente de IA responde com o conhecimento cadastrado, que é genérico por natureza: vale para todos os clientes. Com APIs, ele consulta os seus sistemas no meio da conversa e responde com o dado real daquele cliente: o boleto dele, o plano dele, o pedido dele. E além de ler, pode executar ações, sempre dentro dos limites que você define. Este tutorial cobre o cadastro, o endereço, a autenticação, os parâmetros e as instruções — e todos os lugares onde as APIs trabalham: agentes, fluxos e os canais de atendimento.

Os conceitos: API e Ações

  • API (o sistema): o cadastro de um sistema seu, com a URL base e a autenticação. Ex.: seu ERP, seu CRM, seu sistema de estoque.
  • Ações (o que ele faz): cada coisa que o agente pode buscar ou fazer nesse sistema. Uma API costuma ter várias, e é entre elas que o agente escolhe quando alguém pergunta algo.

Uma distinção atravessa tudo: leitura (consulta dados) e escrita (altera dados). Ação que altera dados é marcada como tal no cadastro e ganha proteções extras, como você verá adiante.

A URL base: só o começo do endereço

No cadastro da API você informa a URL base — o começo que se repete em toda chamada, sem o caminho de cada consulta:

  • certo: https://api.exemplo.com
  • errado: https://api.exemplo.com/clientes/123 (isso é o endereço de uma ação, não da API)

O caminho final entra depois, em cada ação, e o sistema junta as duas partes sozinho: tanto faz digitar com ou sem a barra no começo ou no fim. O campo valida o formato na hora, então endereço com espaço, usuário e senha embutidos ou sem https:// é recusado antes de salvar.

Cadastrando: manual ou com IA

Em Inteligência › Agentes › aba APIs, você cadastra de dois jeitos:

  • Nova API: um assistente em quatro etapas — a API (nome e URL base), o acesso, os parâmetros e as instruções. Só as duas primeiras são obrigatórias; as outras trazem o selo Opcional e podem ficar para depois.
  • Importar com IA (o atalho): cole o link da documentação (OpenAPI/Swagger, coleção do Postman ou uma página de docs) e a IA importa as ações prontas. Em APIs grandes, ela pré-seleciona só as leituras, porque para agentes, poucas ações certas funcionam melhor que dezenas.

Reimportar a documentação atualiza as ações sem apagar o que você escreveu à mão: as instruções editadas por gente são preservadas, e o resultado diz quantas foram mantidas.

Cadastro de uma ação da API

Os três tipos de credencial

A autenticação define em nome de quem a chamada é feita. São três modelos:

  • Credencial fixa: a conta guarda um segredo (token Bearer, chave em header ou usuário e senha) e todas as chamadas usam essa mesma credencial. É o caminho de quase todo mundo: sua API responde como se fosse você perguntando, e quem está na conversa vai junto nos parâmetros.
  • Credencial dinâmica (token do visitante): a chamada vai com o token de quem está na conversa, entregue pelo seu site no widget do chat. Cada cliente enxerga só os próprios dados. É para quem já tem API autenticada por usuário.
  • Sem autenticação: para API pública ou que já filtra por outro caminho. Sem credencial, a proteção passa a ser só do lado da sua API.

Se o token do usuário expira

Na credencial dinâmica, o token é do seu sistema e costuma ter prazo. A conversa, não: ela é retomada por dias no mesmo navegador. Um token colado no código da página vence, e o sintoma aparece longe — o agente dizendo que não conseguiu consultar.

Por isso o seu site entrega uma função no lugar do valor. Ela é chamada quando o token é preciso: ao abrir a conversa, antes de cada envio e no instante em que o seu sistema recusa a credencial.

Chat.init({
key: 'a-chave-do-seu-chat',
credentials: {
// a chave é a mesma que você cadastra aqui, no campo do nome
'X-Auth-Token': () => suaFuncaoQueDevolveOTokenAtual(),
},
})

Recusada a credencial (401 ou 403), a resposta é segurada antes de o agente escrever qualquer coisa: a plataforma pede o token novo, refaz a consulta e entrega a resposta de verdade. Quem perguntou não repete a pergunta nem recarrega a página. Sem a função declarada, a resposta sai explicando que o seu sistema recusou a credencial — o cliente fica sabendo que precisa entrar de novo, em vez de ouvir um erro genérico.

Esse token não se mistura com o contexto livre que o site manda: ele é guardado à parte, cifrado, e não aparece no painel de quem atende a conversa.

O segredo entra e não volta: depois de salvo, ele fica cifrado e nunca é devolvido para a tela, nem para quem tem acesso à configuração. Por isso o campo aparece vazio quando você volta — trocar exige digitar de novo. Ele também não vai para o modelo de IA nem aparece na conversa.

Os três tipos de credencial

Parâmetros: o que vai junto em toda chamada

São dados de contexto que a plataforma anexa a todas as chamadas daquela API, sem você repetir em cada ação. Quase sempre servem para dizer quem está perguntando, para a sua API responder os dados daquela pessoa. Cada linha tem quatro colunas:

  • Nome: a chave que a sua API espera receber, escrita como ela espera (email, cliente_id, X-Api-Version).
  • Valor: de onde a plataforma tira o conteúdo — o e-mail, o telefone, o nome ou o identificador de quem está na conversa; uma chave do data-meta que o seu site manda no widget; ou um valor fixo.
  • Onde: se ele viaja no endereço (query), num cabeçalho (header) ou no corpo (body).
  • Assinar: liga a assinatura HMAC naquele campo.

Um aviso que vale ouro: qualquer um pode digitar um e-mail, e o site pode mandar o que quiser no data-meta. Por isso a plataforma anexa sozinho o campo verified — é nele, e só nele, que a sua API deve confiar para liberar dado privado. Marcando um parâmetro para assinar, vai junto o campo sig, que é a prova de que a chamada saiu daqui: a sua API refaz a conta com o mesmo segredo e compara.

Abaixo dos campos, uma prévia mostra a chamada montada com valores de amostra, exatamente como ela sai. E o botão Ver exemplos abre uma lista do que costuma ser enviado, em forma de tabela.

Instruções: ensine o agente a usar esta API

São orientações, uma por linha, que o agente segue sempre que usar esta API — vale para todas as ações dela. É onde você escreve o que a IA não tem como adivinhar sobre o seu negócio:

  • o vocabulário da casa: o que o cliente quer dizer com "em aberto", "baixar", "fechar o mês";
  • como combinar consultas: quando alguém pede um resumo, quais consultas fazer e em que ordem apresentar;
  • o que nunca fazer: não somar o que entra com o que sai, não misturar períodos diferentes, não apresentar página como total;
  • como se comportar quando falta permissão ou quando o dado não existe.

São opcionais: a API funciona sem elas. Mas é a diferença entre um agente que devolve número solto e um que responde como alguém da sua equipe responderia. O botão Ver exemplos mostra sete grupos de instruções que costumam valer para qualquer sistema.

Onde as APIs trabalham

Nos agentes

Na aba APIs do agente, você escolhe o que aquele agente pode usar. Nada é automático: o agente só alcança o que você marcar.

  • Sistemas que ele consulta: durante a conversa, o agente decide sozinho quando chamar, com base no que o cliente pede.
  • Ações que alteram dados: liberadas uma a uma, e sempre pedem confirmação ao cliente na conversa antes de executar.
  • Modelos: perguntas prontas que aparecem no chat com um clique, só para usuário identificado.
  • Limites: as regras que o agente nunca quebra, uma por linha.

Nos fluxos

No construtor de fluxos, a etapa Consultar API chama uma ação num ponto exato do roteiro (diferente do agente, que decide sozinho). Ela envia variáveis já coletadas como parâmetros, guarda o resultado em variáveis (mais uma variável _ok de sucesso), e tem um ramo próprio se falhar: preencha sempre, para que um sistema fora do ar não roteie a conversa com base numa consulta que não aconteceu. O botão Testar consulta de verdade e deixa você mapear os campos da resposta clicando neles.

Nos canais de atendimento

As APIs valem em qualquer canal onde um agente ou fluxo atende: chat do site, WhatsApp, Instagram, Facebook e e-mail. A identificação do visitante (e, portanto, a credencial dinâmica) é mais rica no chat do site; no WhatsApp, o vínculo vem do pareamento do telefone.

Para testar sem depender do site, use o Testando como (na tela do canal Chat e na prévia do agente): ele mostra um campo para cada dado que as suas APIs leem, e simula inclusive o visitante verificado.

Com Subcontas

Em conversa identificada com uma subconta (quando você repassa o custo de IA aos seus clientes), quem está do outro lado é o cliente do seu cliente — e aí a régua aperta. A ação só roda se as três condições valerem:

  1. É consulta, não escrita. Ação marcada como escrita nunca roda para o usuário final: quem altera o seu sistema é você, não o cliente dele.
  2. A identidade é verificada, não declarada. Precisa da assinatura (auth/sig). E-mail digitado no chat não serve — qualquer visitante digita o de outra pessoa.
  3. A sua API sabe de quem se trata. Ou a credencial é do próprio usuário (token dele na conversa), ou a identidade vai assinada nos parâmetros adicionais, com valor preenchido. Credencial fixa sozinha nunca basta: um token que enxerga todo mundo é exatamente por onde o cliente A leria os dados do B.

Faltando qualquer uma, a ação não aparece para o agente — ele responde com a base de conhecimento e, se precisar, transfere. Não há configuração para afrouxar isso; a regra sai do que a chamada já tem, e é fechada por padrão.

Na prática, o desenho que passa é o mais comum: credencial dinâmica com o token do usuário + identidade assinada. É assim que o isolamento de cada cliente continua sendo do seu sistema, que é quem sabe fazer isso.

Limites e regras

  • Tempo de resposta: cada chamada espera até 15 segundos. Passou disso, o agente trata como falha e segue a conversa (nos fluxos, pelo ramo "se falhar").
  • Tamanho da resposta: o que volta é entregue ao modelo até cerca de 24 KB. Acima disso, a resposta é encolhida e o agente é avisado de que veio cortada — prefira endpoints com filtro e paginação a um que devolve a base inteira.
  • Quantidade de ações: acima de 24 ações ativas no mesmo agente, ele passa a buscar a ação certa em vez de receber todas de uma vez. Funciona, mas com muitas ações a escolha fica mais difícil: prefira um agente por assunto a um agente com tudo.
  • Endereços internos são bloqueados: URLs que apontam para a rede privada ou para o próprio servidor não são chamadas. Exponha o endpoint na internet, com autenticação.
  • Escrita pede confirmação e nunca roda para o cliente final em conversa de subconta.

Muitas ações? Um fluxo com um agente por assunto

O limite de 24 costuma aparecer em quem conecta um sistema grande — só o módulo financeiro já passa disso. A saída não é ter um canal de chat para cada assunto, e sim um fluxo de entrada no lugar do agente:

  1. O chat aponta para o fluxo (no card Quem atende), não para um agente.
  2. O fluxo faz a triagem — por menu ou pelo que já sabe de quem chegou.
  3. Cada caminho leva ao agente daquele assunto, cada um com as suas ações e as suas instruções.

Para quem está do outro lado continua sendo um chat só. Por dentro, cada agente enxerga um punhado de ações que ele sabe escolher, em vez de uma lista onde tudo se parece. As credenciais seguem valendo: o token de quem está na conversa atravessa o fluxo e chega ao agente que atender.

O que a sua ação devolve

O agente lê a resposta e escreve com ela — inclusive montando tabela quando os dados pedem, e gráfico quando ajuda a entender. O visitante baixa isso em Excel ou PDF por um botão na própria mensagem, sem nada ser salvo em servidor nenhum.

O que não existe é devolver arquivo binário na resposta da ação: um PDF ou uma planilha que a sua API gere não vira anexo da conversa. Devolva a URL do arquivo, e o agente entrega o link — que também é o caminho certo para o controle de acesso continuar sendo seu.

Boas práticas

  1. Poucas ações certas batem dezenas de genéricas: importe só o que o atendimento usa.
  2. Escreva as instruções da API: elas valem para todas as ações e economizam repetição.
  3. Escreva bem as instruções de cada ação: é por elas que a IA decide qual chamar.
  4. Prefira leitura: marque como "altera dados" só onde a confirmação do cliente faz sentido.
  5. Não sirva dado privado sem identidade verificada: exija o verified, de preferência com assinatura.
  6. Acompanhe o uso: a coluna de uso e erros dos últimos 7 dias mostra o que está quebrando antes de o cliente reclamar.

Muitas ações: acima de duas dezenas, o agente passa a procurar

Enquanto o agente tem até 24 ações liberadas, ele recebe todas de uma vez e escolhe lendo as instruções de todas. Passando disso, ele muda de método: em vez de carregar o catálogo inteiro a cada mensagem, ele procura pelo que a pessoa pediu e chama o que encontrar.

A mudança é automática e não tem botão. O que ela muda para você é a régua do que escrever:

  • As instruções viram o que faz a ação ser encontrada, e não só o critério de escolha. Escreva com as palavras que o cliente usa, porque é por elas que a busca acha.
  • Ações quase iguais atrapalham mais: numa lista de dezenas, duas instruções parecidas viram um sorteio. Diga em cada uma quando não usar e qual usar no lugar.
  • Libere no agente só o que aquele atendimento usa. Um sistema com centenas de ações cadastradas continua funcionando, mas o agente responde melhor com as poucas certas na mesa.

Vale para o total de ações liberadas naquele agente, somando todas as APIs, e não para o que está cadastrado na conta.