Chamar API

O agente Chamar API executa requisições HTTP usando URL, corpo JSON, método (GET, POST, PUT, DELETE, etc.) e token de autenticação, permitindo integrações e operações CRUD de forma segura.

Use este agente quando precisar que o avatar consulte ou registre informações em sistemas externos durante a conversa, como CRMs, ERPs, bases de dados ou qualquer serviço que exponha uma API REST.

​

Instruções para geração automática (opcional)

Campo de texto onde você descreve, em linguagem natural, como o formulário deve ser preenchido. A IA usa essa descrição para propor automaticamente URL, Body, Headers, método HTTP e demais campos ao clicar em Preencher formulário com IA.

Bloco de instruções para geração automática do formulário do agente Chamar API

​

Quando usar este campo

• Primeira configuração de um agente, quando você ainda não sabe exatamente como montar a requisição.
• Padronização: quando quer que vários agentes sigam o mesmo padrão de URL, autenticação e tratamento de resposta.
• Documentação viva: o texto serve também como explicação para outras pessoas que forem revisar o fluxo.

​

O que descrever

• Objetivo da chamada (o que a API faz e em que momento da jornada é usada).
• Endpoint e método esperados (ex.: GET /pedidos/:numeroPedido ou POST /leads).
• De onde vêm os dados (quais campos serão extratos da conversa ou do contexto).
• Regras e validações (formatos aceitos, campos obrigatórios, limites).
• O que deve aparecer para o usuário na resposta final.

​

Exemplos de preenchimento

Consulta de pedido (GET):

A API de pedidos está em https://api.loja.com/pedidos. Para consultar um pedido, o endpoint é GET /pedidos/:numeroPedido. O número do pedido deve ser extraído da mensagem do usuário (formato: 6 dígitos, apenas números). A autenticação usa Bearer token no header Authorization. Em caso de sucesso, retornar apenas status, data prevista de entrega e valor total. Se o pedido não existir, informar de forma educada que não foi encontrado.

Criação de lead em CRM (POST):

Quero criar um lead no CRM usando POST https://api.crm.com/leads. O body deve conter nome completo, e-mail e telefone, extraídos da conversa. Nome é obrigatório, e-mail deve ser válido (formato com @) e telefone deve ter DDD + 9 dígitos. Se algum dado faltar, peça ao usuário antes de chamar a API. Na resposta, mostre apenas o identificador do lead criado e uma mensagem de confirmação.

Atualização de status de ticket (PATCH):

A API de tickets está em https://api.suporte.com/tickets/:ticketId. Usar método PATCH para atualizar o campo status. O ticketId vem da conversa anterior ou do contexto do atendimento. O novo status deve ser uma das opções: "aberto", "em_andamento" ou "fechado". Se o usuário pedir um status inválido, explique as opções disponíveis. Na resposta, confirme o novo status e a data da atualização.

​

Boas práticas

• Escreva como se estivesse orientando outra pessoa, não a máquina.
• Seja específico com formatos (tamanho, tipo, exemplos de valores).
• Indique o que fazer em caso de dado ausente ou inválido (ex.: pedir novamente, cancelar a chamada).
• Evite colocar segredos (tokens, senhas) diretamente no texto; deixe apenas instruções de onde eles devem ser configurados.

Quanto mais detalhado e específico for o texto, melhor o resultado da geração automática.

​

Campos principais

​

URL (obrigatório)

Endereço completo do serviço externo que será chamado. Pode incluir segmentos dinâmicos no caminho, no formato :nomeDoCampo, que serão preenchidos automaticamente com os dados extraídos da conversa ou do contexto.

Exemplos:

https://api.minhaempresa.com/v1/pedidos/:numeroPedido
https://api.crm.com/leads/:leadId/atualizar
https://api.erp.com/produtos?categoria=:categoria

Se a URL for https://api.exemplo.com/clientes/:cpf e o campo cpf for capturado como 123.456.789-00, a requisição será feita para https://api.exemplo.com/clientes/123.456.789-00.

​

Body

Dados enviados no corpo da requisição, em formato JSON. Por padrão, todos os campos definidos aqui são incluídos no corpo da mensagem.

Comportamento:

• Se houver segmentos dinâmicos na URL (ex.: :numeroPedido), os valores correspondentes substituem automaticamente essas partes no caminho e não são enviados no body.
• Se a opção Query Params estiver ativada, os campos que não forem usados como segmentos dinâmicos na URL serão enviados como parâmetros de consulta (query string), usando o nome de cada campo como chave.

Campos com valor fixo:

Cada campo no Body pode ter um valor pré-definido. Quando um valor fixo é configurado, ele é enviado diretamente na requisição sem ser extraído da conversa. Útil para tokens internos, identificadores de sistema ou parâmetros que nunca mudam.

Exemplo de preenchimento (POST para criar pedido):

{
  "clienteId": "(extraído da conversa)",
  "produtos": [
    { "sku": "PROD-001", "quantidade": 2 }
  ],
  "observacao": "Pedido via chat"
}

No exemplo acima, clienteId será extraído da conversa pela IA, enquanto produtos e observacao possuem valores fixos e são enviados tal qual.

Exemplo para consulta com dados da conversa (Body vazio ou mínimo para GET):

Para requisições GET, o body costuma ficar vazio. Os parâmetros dinâmicos podem ir na URL ou, com Query Params ativado, como query strings.

​

Campos obrigatórios e dados faltantes

Cada campo definido no Body pode ser marcado como obrigatório. Quando o agente não consegue extrair um campo obrigatório da conversa:

1. A chamada à API não é realizada.
2. O avatar recebe uma instrução automática pedindo o dado ao usuário.
3. Na próxima mensagem do usuário, o agente tenta novamente a extração.

Isso garante que a API nunca receba dados incompletos, mas exige que os campos obrigatórios sejam bem descritos para a IA saber o que procurar.

​

Método de requisição HTTP

Método HTTP a ser usado na requisição. Os mais comuns:

Exemplo: Para consultar status de pedido, use GET. Para registrar um lead em um CRM, use POST.

​

Headers

Lista de cabeçalhos HTTP no formato Nome: Valor. Digite cada par em uma linha e pressione Enter para adicionar. Essenciais para autenticação e configuração da requisição.

Exemplos de preenchimento:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
X-API-Key: sua-chave-api
Accept: application/json

​

Models

Modelo de IA utilizado para extrair dados da conversa ao montar o body da requisição.

Formato: provider/nome-do-modelo (ex.: openai/gpt-4.1-mini). Se apenas o nome for informado sem provider, o padrão é OpenAI.

Modelo padrão: gpt-4.1-mini (quando nenhum modelo é selecionado).

Modelos mais capazes (como gpt-4.1) podem melhorar a extração de dados complexos, mas têm maior custo e latência. Escolha conforme a complexidade da extração desejada.

​

Opções de comportamento

​

IP Fixo

Quando ativado, a requisição é realizada usando um IP fixo. Útil quando a API externa exige whitelist de IPs para segurança.

​

Chamada assíncrona

Quando ativado, a requisição é disparada em segundo plano. Características:

• O fluxo da conversa continua imediatamente, sem aguardar resposta.
• O conversationId é incluído automaticamente no body da requisição, para que o sistema externo saiba a qual conversa o resultado se refere.
• A continuidade depende de notificação externa (webhook ou callback configurado em outro lugar).
• Nenhum resultado é retornado ao avatar nesta execução.

Quando desativado (padrão), a resposta da API é aguardada e processada imediatamente antes de prosseguir.

Use assíncrono quando: a API demora muito para responder, ou o processo é disparado e o resultado chega por outro canal.

​

Query Params

Quando ativado, os campos que não forem utilizados como segmentos dinâmicos na URL serão enviados como parâmetros de consulta (query string), usando o nome de cada campo como chave.

Exemplo: URL https://api.exemplo.com/busca, Body com { "termo": "notebook", "limite": 10 } e Query Params ativado resulta em:

GET https://api.exemplo.com/busca?termo=notebook&limite=10

​

Múltiplas chamadas

Quando ativado, o agente faz uma requisição separada para cada elemento de um array presente nos dados. Útil para processar listas (ex.: vários pedidos, vários IDs).

Exemplo: Se os dados contiverem { "pedidos": ["101", "102", "103"] } e Múltiplas chamadas estiver ativado, serão feitas 3 requisições, uma para cada número de pedido.

​

Tratamento de resposta e erros

​

Instruções prioritárias via resposta da API

A API externa pode incluir instruções de alta prioridade diretamente no JSON de resposta usando chaves reservadas. Quando o agente detecta uma dessas chaves, o valor é extraído automaticamente do resultado, removido dos dados exibidos e adicionado como instrução crítica para o avatar com prioridade máxima.

Chaves reconhecidas (case-insensitive):

Variações de caixa e separadores (_, -) são aceitas: Realtime_Instructions, instrucao, REALTIMEINSTRUCTIONS etc.

Comportamento:

• O valor pode ser uma string ou um array de strings. Arrays são concatenados automaticamente.
• A instrução extraída recebe prioridade crítica e peso máximo (10) no sistema interno de instruções, o que significa que ela aparece antes de todas as outras instruções no contexto do avatar — incluindo instruções do prompt base, regras de automação e outros agentes.
• Os dados restantes da resposta continuam sendo processados normalmente (filtro por LLM, inserção no diálogo etc.).

Exemplo de resposta da API:

{
  "pedido": { "id": 45678, "status": "enviado" },
  "realtimeInstructions": "Informe que o prazo de entrega foi antecipado para amanhã."
}

Neste caso, o avatar recebe a instrução "Informe que o prazo de entrega foi antecipado para amanhã." com prioridade máxima, e os dados do pedido são processados separadamente.

​

Instruções de sucesso

Orientações para a IA filtrar e formatar a resposta da API. O comportamento varia conforme o tamanho da resposta:

Até 4096 tokens (~16 KB de texto): o resultado é entregue diretamente ao avatar, sem processamento LLM adicional. As instruções de sucesso não são aplicadas.

Acima de 4096 tokens: a resposta é processada por um LLM (gpt-4.1-mini) que filtra e simplifica os dados conforme as instruções de sucesso, usando também o contexto da conversa para manter apenas os dados relevantes.

Para APIs que retornam JSONs pequenos, o avatar recebe o resultado integral. As instruções de sucesso só são úteis quando a resposta é grande o suficiente para precisar de filtragem.

Exemplo de preenchimento:

Extraia e exiba apenas: status do pedido, data prevista de entrega e valor total. Ignore dados internos, IDs técnicos e metadados. Se houver lista de itens, mostre apenas os nomes e quantidades.

​

Armazenar resposta no Cache

Quando ativado, armazena o resultado da requisição por até 24 horas. Se a API apresentar erro durante esse período, o valor armazenado será usado como fallback, evitando que a conversa fique sem retorno.

Use em APIs instáveis ou com rate limit, para melhorar a resiliência do fluxo.

​

Tratamento de exceções

​

Mensagem de erro

Texto exibido à IA quando a requisição falha (timeout, erro 4xx/5xx, conexão recusada, etc.). Use para orientar como o avatar deve responder ao usuário nessa situação.

Exemplo de preenchimento:

O sistema de pedidos está temporariamente indisponível. Peça ao usuário para tentar novamente em alguns minutos. Se o problema persistir, sugira que entre em contato pelo telefone 0800-XXX-XXXX ou pelo e-mail suporte@empresa.com.

Boas práticas:

• Seja claro e acolhedor: evite termos técnicos como “erro 500” ou “timeout”.
• Ofereça alternativas concretas (retentar, outro canal, horário de atendimento).
• Se a falha for esperada em certas condições (ex.: pedido não encontrado), oriente a IA a explicar isso de forma amigável.

​

Cenários comuns de falha

​

Inserção no diálogo

​

Inserir no diálogo

Define como os dados retornados pela API são incorporados ao contexto da IA e por quanto tempo ficam disponíveis:

• Verdadeiro: os dados processados são inseridos diretamente no diálogo, ficando visíveis para a IA na mensagem atual e em todas as próximas requisições. Funciona como uma mensagem permanente no histórico da conversa.
• Falso: os dados são fornecidos como instruções em tempo real para a IA, porém ficam disponíveis apenas na requisição da mensagem atual. Nas próximas mensagens, essas instruções não estarão mais presentes no contexto.

Use verdadeiro quando a informação precisar persistir no histórico da conversa para referência futura (ex.: dados de um pedido que o usuário pode perguntar novamente). Use falso quando a informação for relevante apenas para compor a resposta imediata e não precisar ser lembrada depois.

​

Dados e captura

​

Instruções de captura

Orientações para extrair os dados da conversa e montar o objeto enviado no body da requisição (ou nos segmentos dinâmicos da URL). A IA usa o modelo configurado em Models para fazer essa extração.

Exemplo de preenchimento:

Extraia da conversa: (1) número do pedido, que o usuário pode informar como "pedido 12345" ou apenas "12345"; (2) CPF do cliente, se mencionado, no formato apenas números. O número do pedido é obrigatório. Se o usuário não informar o pedido, a IA deve pedir antes de chamar a API.

​

Confiança na extração (Trust Score)

Ao extrair dados da conversa, a IA atribui um score de confiança (0 a 10) indicando o quanto ela tem certeza de que os dados extraídos estão corretos.

• Score 6 ou acima: extração considerada confiável, a chamada prossegue normalmente.
• Score abaixo de 6: registrado nos logs internos como “trust baixo”. A chamada ainda é realizada, mas o resultado pode ser impreciso.

Use descrições detalhadas nos campos do Body e nas Instruções de captura para aumentar a confiança da extração.

​

Dados Realtime

Lista de dados a serem buscados no processamento da requisição e enviados no body. Digite cada item e pressione Enter para adicionar. Útil para incluir informações do contexto em tempo real.

Campos disponíveis:

Exemplo: Adicionar conversationId e leadId para que esses valores do contexto sejam incluídos automaticamente no body.

​

Exemplo completo de configuração

Cenário: Consultar status de pedido em sistema externo.

​

Solução de problemas