Requisição HTTP Personalizada

Monta e executa uma requisição HTTP completa diretamente no fluxo. Este node deve ser usado dentro de fluxos do bot, sempre conectado a uma jornada com objetivo claro, rota esperada e tratamento para exceções.

Quando usar

• Use quando a requisição precisa ser configurada por completo dentro do próprio node.
• Aplique para consultar ou enviar dados a uma API e escolher o próximo caminho pelo status ou conteúdo da resposta.

Campos de configuração

• Nome da requisição: identificação opcional exibida no próprio node.
• Método e URL: escolha GET, POST, PUT, PATCH, DELETE ou HEAD e informe um endereço HTTP ou HTTPS.
• Parâmetros: valores adicionados à query string da URL.
• Autenticação: sem autenticação, Bearer token, Basic ou API Key em header ou query.
• Headers: cabeçalhos adicionais; use o cadeado para valores sensíveis.
• Body: vazio, JSON, URL encoded ou Raw, conforme o método selecionado.
• Status HTTP aceitos: faixa que define uma resposta de sucesso, como 200-299.
• Variável de saída: nome usado para disponibilizar o body retornado aos próximos nodes.
• Validação do conteúdo: condição opcional aplicada a um caminho do body.
• Timeout: tempo máximo entre 1 e 30 segundos.
• Redirecionamentos: permite seguir até três redirecionamentos.

Entradas e saídas

• Entradas: recebe 1 entrada.
• Saídas: possui 3 saídas.
• Sucesso: usada quando o status HTTP e a condição opcional do body são aceitos.
• Resposta não aceita: usada quando o endpoint responde, mas o status ou o conteúdo não atende à regra configurada.
• Erro técnico: usada em URL inválida, timeout, falha de rede ou configuração incorreta.

Exemplo prático

Consulte um pedido em uma API própria, envie dados da conversa no body e direcione o fluxo conforme a resposta recebida.

Ampliar

Na imagem, o body Contexto está selecionado para enviar a conversa e as variáveis atuais sem montar o JSON manualmente.

Onde configurar

Acesse Fluxos do bot na plataforma. No menu lateral, abra Mensageria > Configurações e, na árvore de configurações, selecione Bots > Fluxos Automáticos.

Abra ou crie um fluxo. No canvas, adicione Requisição HTTP Personalizada no grupo Dados e integrações e conecte a entrada e as três saídas antes de publicar.

Montar a requisição

1. Defina um nome curto que identifique a finalidade da integração.
2. Escolha o método e informe a URL. Variáveis podem ser usadas também no endereço.
3. Adicione parâmetros, autenticação e headers somente quando o endpoint exigir.
4. Para métodos com conteúdo, escolha JSON, URL encoded ou Raw e monte o body.
5. Na aba Resposta, defina quais status são aceitos, a variável de saída e, se necessário, uma condição sobre o body retornado.

Se você já recebeu um comando cURL, use Importar cURL para preencher a configuração inicial. Revise método, URL, autenticação, headers, parâmetros e body antes de testar.

Escolher o node HTTP correto

Usar variáveis na requisição

Use o botão Inserir variável nos campos compatíveis. O seletor inclui variáveis padrão e valores criados por nodes anteriores no mesmo fluxo. Variáveis definidas por um Agente de IA também podem ser usadas individualmente depois que forem criadas.

Enviar a conversa e todas as variáveis

Quando o endpoint precisar do estado completo, abra Body e escolha Contexto. O node monta automaticamente um JSON com esta estrutura:

{
  "room": {},
  "vars": {}
}

• room recebe o conteúdo completo e atualizado da conversa.
• vars recebe todas as variáveis acumuladas até aquele ponto, inclusive valores criados por nodes anteriores e por Agentes de IA.

O modo Contexto é indicado quando a API deve receber o conjunto completo. Para enviar apenas campos específicos, continue usando JSON ou Raw com o seletor de variáveis. Nesses formatos, {{room}} pode representar a conversa inteira.

Preparar os dados de teste

Ao testar o body Contexto, o editor começa com dados fictícios no formato room e vars. Ajuste-os para reproduzir o cenário desejado:

{
  "room": {
    "_id": "conversa-exemplo",
    "chId": "usuario-whatsapp-exemplo",
    "status": "opened"
  },
  "vars": {
    "intencao": "segunda_via",
    "resumoAtendimento": "Cliente solicitou uma nova via da cobrança."
  }
}

Esses valores são usados somente na execução do teste e não ficam salvos no fluxo.

Configurar a regra de resposta

Por padrão, respostas entre 200 e 299 seguem pela saída Sucesso. Você pode informar outras faixas separadas por vírgula e validar também um caminho do body, como data.success.

As condições disponíveis verificam se o campo existe, não está vazio, contém uma lista com itens, é igual ou é diferente do valor esperado. Quando o status ou a condição não forem aceitos, o fluxo segue por Resposta não aceita.

Se Variável de saída for preenchida, o body retornado fica disponível para os próximos nodes.

Proteger credenciais e dados

• Marque como sensíveis tokens, senhas, chaves e outros valores secretos configurados em autenticação, parâmetros, headers ou body URL encoded.
• Ao salvar o fluxo, valores protegidos são armazenados com segurança e aparecem mascarados nos detalhes do teste.
• Prefira endpoints públicos com HTTPS. Endereços locais ou de rede privada não podem ser chamados pelo node.
• Envie somente os campos necessários. O body Contexto pode reunir dados criados por vários nodes; revise o conteúdo antes de encaminhá-lo para uma API externa.
• Se usar {{room}}, confirme se o endpoint realmente precisa receber o objeto completo da conversa.

Boas práticas e riscos comuns

• Prefira HTTPS e envie credenciais por autenticação ou header protegido.
• Envie apenas os dados necessários; o body Contexto inclui as variáveis acumuladas e o objeto completo da conversa.
• Conecte as três saídas para evitar que a conversa fique sem tratamento em rejeições ou erros.
• Não presuma que chId seja um telefone; no WhatsApp, ele pode representar o identificador do usuário ou o telefone, conforme a conversa.

Como testar

• Informe método e URL e clique em Testar.
• Preencha no modal um objeto JSON com valores fictícios para todas as variáveis usadas na requisição.
• Execute casos de sucesso, resposta não aceita e erro técnico.
• Confira body, headers, tempo de resposta e requisição resolvida; valores sensíveis devem aparecer mascarados.
• O teste exige acesso de administrador e não salva o fluxo nem os dados customizados.

Guias relacionados

• Chamada em API Externa
• Requisição HTTP (Webhook)
• Requisição HTTP (Delegar)
• Nodes de fluxos do bot
• Guia geral de fluxos do bot
• Fluxos do bot
• Cenários comuns de fluxos do bot