Ações da API: endereço, parâmetros, resposta e instruções

Ação é cada coisa que o agente pode buscar ou fazer na sua API durante a conversa: consultar uma situação, confirmar um cadastro, ver um horário, registrar um pedido. Uma API costuma ter várias, e é entre elas que o agente escolhe quando alguém pergunta algo. Sem nenhuma, a API está conectada mas o agente não tem o que chamar.

Este artigo cobre as quatro etapas do cadastro de uma ação: a ação (nome e endereço), parâmetros, resposta e instruções. Só a primeira é obrigatória — as outras três trazem o selo Opcional.

1. A ação: nome e endereço

O nome é para você: escreva como chamaria a ação numa conversa ("consultar situação do cadastro").

O endereço se monta em duas partes. O começo vem da API e é igual em todas as ações; aqui você escreve só o pedaço final. A linha abaixo dos campos mostra a chamada montada, do jeito que ela sai:

  • /clientes → a lista inteira
  • /clientes/{id} → um cadastro só
  • /relatorios/vendas → caminho fixo, nada a preencher
  • em branco → a API tem um endereço único

O trecho entre chaves é a parte que muda: escrever {id} é dizer "aqui entra o valor daquele atendimento", e o agente preenche na hora com o que apurou na conversa. Muita ação não precisa de nenhuma chave.

Filtro não vai no caminho. Período, situação e página não se escrevem como ?campo=valor: eles são declarados na etapa de parâmetros, e a plataforma os envia sozinho — assim o agente sabe que pode preenchê-los, em vez de tentar adivinhar um endereço.

Buscar ou alterar

O método fica ao lado do caminho: GET busca informação; os outros criam, alteram ou apagam, e ao escolher um deles aparece o campo do corpo da requisição, que é o pacote de dados enviado junto.

Logo abaixo há a chave "Esta ação altera dados no sistema". Ligada, o agente não executa direto: ele pede a confirmação do cliente dentro da conversa — é o que impede um cadastro alterado por engano. Ela é separada do método de propósito: nada impede uma API de apagar algo por GET, então quem sabe o que a chamada faz do outro lado é você, não o método.

O que o cliente vê antes de confirmar

O pedido aparece como um cartão na conversa, com o nome da ação, o lembrete de que nada muda até ele decidir e dois botões: Confirmar e Agora não. Depois da decisão o cartão vira uma linha de histórico — Feito, Você cancelou ou Não deu certo — e o agente escreve o desfecho na conversa.

Por isso o nome da ação importa mais do que parece: é ele que o cliente lê. "Enviar orçamento por e-mail" diz o que vai acontecer; uma sigla ou o nome do endereço não dizem nada. O endereço da chamada, os parâmetros e as instruções que você escreveu para a IA não aparecem para o cliente: são bastidor e ficam no servidor.

A chamada só sai depois do Confirmar, e sai com a identidade daquela conversa: se a sua API exige o token do usuário, é o token dele que vai. Quem não pode fazer aquilo no seu sistema continua não podendo pelo chat.

2. Parâmetros: o que a ação precisa saber

Cada parâmetro é uma pergunta que o agente responde sozinho, com o que apurou na conversa. A tabela tem cinco colunas, e cada cabeçalho traz um ícone de ajuda explicando o que ele significa:

  • Nome: a chave que a sua API espera receber, escrita como ela espera.
  • Tipo: texto, número inteiro, número decimal ou sim/não. É o que impede o agente de mandar "vinte" onde a API quer 20.
  • Instrução para a IA: quem lê é a IA. Descreva o formato esperado — "primeiro dia do período, no formato AAAA-MM-DD", "CPF ou CNPJ, só números" —, porque é isso que evita a chamada que volta erro.
  • Opções: quando o valor só pode ser um entre poucos, liste-os separados por vírgula. O agente para de inventar e passa a escolher.
  • Obrigatório: diz ao agente que, sem aquilo, não adianta chamar — ele pergunta ao cliente antes, em vez de tentar e falhar.

Abaixo da tabela, uma prévia mostra a chamada montada com os valores de exemplo. O botão Ver exemplos abre uma lista dos parâmetros que costumam existir — encontrar um registro, recortar por período, escolher entre opções fixas, buscar e limitar.

3. Resposta: o que volta para o agente

A resposta da sua API não vai para o cliente: vai para o agente ler. Em branco, ele recebe tudo, do jeito que a sua API devolveu — e esse é o começo certo.

Se a resposta vier grande ou cheia de campo interno, liste em Campos a manter o caminho de cada campo que importa, com ponto entre os níveis e vírgula entre eles: data.status, data.total. Não é economia, é precisão: resposta enorme faz o agente se perder entre campos parecidos (valor, valor_bruto, valor_liquido) e responder com o errado.

Se a resposta for uma lista, use * no lugar do índice para dizer "cada item": data.itens.*.codigo, data.itens.*.quantidade mantém só esses dois campos de cada item. O campo dentro da lista também pode ser escolhido clicando nele na prévia da resposta. Recorte dentro de lista dobra o limite de tamanho, então mais registros chegam inteiros ao agente — e, se mesmo assim passar do limite, a plataforma poda registros e avisa o agente de que o resultado é parcial.

Consultas independentes (o estoque de dez produtos, por exemplo) o agente passou a fazer de uma vez, em vez de uma por rodada: a resposta chega em segundos, não em minutos.

4. Instruções: quando o agente deve usar esta ação

É por este texto que o agente escolhe esta ação entre todas as outras. Duas coisas fazem toda a diferença:

  1. Quando usar, com as palavras do cliente. O agente compara a frase de quem está na conversa com o que você escreveu. Por isso descrever a situação funciona melhor que descrever o retorno técnico: "use quando pedirem a situação de um cadastro" ensina mais que "retorna o registro pelo id".
  2. Quando NÃO usar. É a parte que quase todo mundo pula, e a que mais evita erro. Se existe uma ação parecida que confunde, diga qual usar no lugar: "use para um cadastro; para a lista toda, use listar_clientes". Sem isso, o agente responde outra pergunta com cara de resposta.

A régua entre os dois lugares: o que vale para todas as ações da API — vocabulário, como combinar consultas, o que nunca concluir — fica nas instruções da API. Aqui entra só o que é desta ação.

Uma instrução por linha. O campo funciona como uma lista: cada linha é uma regra. Na linha com conteúdo aparece o ícone Organizar com IA, que reescreve só aquela instrução — sem mexer nas outras. O botão Ver exemplos traz modelos prontos de quando usar, quando não usar, parâmetros, resposta e escrita, e o contador mostra o limite de 5.000 caracteres.

O contexto do site pode entrar na regra. Quando o chat do seu site envia o contexto livre (data-meta), o agente vê cada chave como visitor.<chave> — e a instrução pode citá-la como valor padrão de um parâmetro: "quando o cliente não pedir uma unidade específica, preencha o parâmetro com o visitor.unidade". O que o cliente pedir na conversa vence, e o contexto não vale como prova de acesso. Os detalhes de como o site envia esses dados estão em Referência: o que o chat envia e o que a sua API recebe.

O cliente nunca vê este texto: é instrução interna, escrita para o agente.

Depois de criada

A ação já nasce ativa. Na tela de edição, os cards abrem um de cada vez e há a chave para desativá-la: ela some da mesa do agente sem ser apagada, o que serve para tirar do ar algo que está devolvendo erro. Na lista, cada ação mostra o uso e os erros dos últimos 7 dias, e o menu ⋮ traz testar, duplicar, ativar/desativar e excluir.

O botão Testar chama a ação de verdade, com valores de exemplo — é o jeito mais rápido de descobrir que faltou um parâmetro ou que o endereço está errado, antes de um cliente descobrir por você.