Parâmetros de entrada, body template, headers e mapeamento de resposta
Como definir os dados que o agente envia à sua API e como extrair da resposta apenas o valor de que ele precisa.
Veja este passo no vídeo · Ações personalizadas: parâmetros, variáveis e teste
Para que serve esta configuração
Depois de criada a ação, estes quatro blocos definem o que o agente envia para a sua API e o que retorna à conversa: os parâmetros de entrada, o body template, os headers e o mapeamento de resposta. Configurá-los bem é o que torna a integração confiável.
Parâmetros de entrada (input_schema)
São os valores que o modelo deve preencher antes de chamar o endpoint. Na seção Parâmetros de entrada, clique em Adicionar parâmetro e defina para cada um:
- Nome: o identificador do campo (ex.:
email,plano_id). - Tipo:
string,number,boolean,emailouphone. - Descrição: explique o que é; o modelo a usa para preencher o valor certo.
- Obrigatório: marque a caixa se o agente não puder chamar a ação sem esse dado.
O modelo deduz esses valores a partir da conversa, então uma boa descrição (ex.: "e-mail do cliente para buscar o pedido") melhora muito a precisão.
Body template
É o corpo enviado nos métodos POST, PUT ou PATCH (não é usado em GET). Escreva em JSON, com variáveis substituídas na execução:
{
"email": "{{input.email}}",
"canal": "{{contact.email}}"
}
{{input.nome}}insere um parâmetro de entrada.{{contact.email}}e outros campos do contato inserem dados de quem está conversando.
Se você declarar um header Content-Type: application/json, o body é enviado como JSON; caso contrário, é enviado como texto puro.
Headers
Em Headers, clique em Adicionar header e adicione pares chave/valor. O mais comum é a autenticação:
Authorization→Bearer SEU_TOKENContent-Type→application/json
Você pode definir até 20 headers. Os valores também aceitam variáveis {{...}}.
Campo a extrair (response_mapping)
Sua API costuma responder um JSON grande, mas o agente só se importa com um valor. Em Campo a extrair (response_mapping), informe o caminho com pontos até esse dado:
- Resposta
{"data": {"plans": [...]}}→ escrevadata.plans. - Se deixar vazio, o agente recebe a resposta completa.
Isso mantém o contexto do modelo limpo e focado só no que é útil.
Verificação
- Cada parâmetro obrigatório aparece com a caixa Obrigatório marcada.
- O Body template é JSON válido (chaves balanceadas) e usa apenas variáveis existentes.
- Após Salvar ação, use Testar para confirmar que sua API recebe os campos e que Campo a extrair aponta para o valor certo.
Se não funcionar
- Um dado chega vazio: verifique se o nome da variável
{{input.x}}coincide exatamente com o Nome do parâmetro. - Sua API rejeita o body: adicione o header
Content-Type: application/jsone valide se o JSON está bem formado. - O agente retorna "informação demais": defina o Campo a extrair para ficar só com o valor necessário.
Dica: comece com poucos parâmetros e apenas os Obrigatórios essenciais. Quanto menos valores o modelo tiver que adivinhar, mais confiável fica.
Dica: nunca coloque tokens na URL; coloque-os em Headers (
Authorization).
Artigos relacionados
Artigos relacionados
-
Crie seu primeiro agente de IA
Aprenda o que um agente de IA faz no Omnifox, como dar instrucoes, conecta-lo a um canal e testa-lo no sandbox antes de falar com clientes reais.
-
Como escrever boas instruções para seu agente de IA
Aprenda a redigir instruções claras para que seu agente de IA responda com o tom, os limites e as ações corretas.
-
Guia completo dos Agentes de IA
Os Agentes de IA a fundo, em 65 capítulos: criar, instruções, ferramentas, conhecimento, comportamento, teste, caixa de entrada, fluxos, análise e consumo, com cada opção explicada.
-
Conectar seu agente de IA ao WhatsApp, Instagram, Messenger e chat do site
Um agente sem canais não atende ninguém. Conecte-o ao seu WhatsApp, Instagram, Messenger ou ao chat do seu site na seção Conexões e ative-o para ele começar a responder.
-
Comece aqui: os Agentes de IA em 8 minutos
O essencial dos Agentes de IA em um vídeo curto: criar um agente, as instruções, ferramentas, conhecimento, canais, o teste, o horário e a passagem para uma pessoa.