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.

Jun 26, 2026

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, email ou phone.
  • 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_TOKEN
  • Content-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": [...]}} → escreva data.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/json e 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

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp