# Agilize Docs para IA - Página atual

Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize.
Use esta versão quando a pergunta do usuário estiver restrita ao documento atual.

Última geração: 2026-08-29T23:38:59.707Z

## Página

- Título: Requisição HTTP Personalizada
- URL humana: https://agilize.app/docs/configuracao/referencias/nodes-fluxos-do-bot/requisicao-http-personalizada
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Monta e executa uma requisição HTTP completa diretamente no fluxo.

## Seções

- Quando usar
- Campos de configuração
- Entradas e saídas
- Exemplo prático
- Onde configurar
- Montar a requisição
- Escolher o node HTTP correto
- Usar variáveis na requisição

## Conteúdo da página

# 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.

![Configuração do node Requisição HTTP Personalizada com o body Contexto selecionado](/docs/screenshots/config-fluxos-bot-node-requisicao-http-personalizada.png)

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](https://my.agilize.app/messenger/bot/flow). 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

| Necessidade | Node recomendado |
| --- | --- |
| Configurar método, URL, autenticação, parâmetros, headers, body e regra de resposta no próprio fluxo | **Requisição HTTP Personalizada** |
| Usar uma operação de integração já cadastrada na plataforma | **Chamada em API Externa** |
| Enviar o estado da conversa sem depender do retorno para decidir o caminho | **Requisição HTTP (Webhook)** |
| Entregar o controle da conversa a um serviço próprio, com retorno de mensagens e variáveis | **Requisição HTTP (Delegar)** |

## 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.

| Variável | Conteúdo |
| --- | --- |
| `{{name}}` | Primeiro nome do contato. |
| `{{case}}` | Protocolo atual da conversa. |
| `{{chId}}` | Identificador atual da conversa no canal. No WhatsApp, pode ser o identificador do usuário ou o telefone. |
| `{{room}}` | Objeto completo da conversa. Subcampos podem ser acessados, como `{{room._id}}`. |
| `{{whatsapp.userId}}` | Identificador do usuário no WhatsApp. |
| `{{whatsapp.phone}}` | Telefone do WhatsApp, quando disponível. |

### 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:

```json
{
  "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:

```json
{
  "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](/docs/configuracao/referencias/nodes-fluxos-do-bot/chamada-em-api-externa)
- [Requisição HTTP (Webhook)](/docs/configuracao/referencias/nodes-fluxos-do-bot/requisicao-http-webhook)
- [Requisição HTTP (Delegar)](/docs/configuracao/referencias/nodes-fluxos-do-bot/requisicao-http-delegar)
- [Nodes de fluxos do bot](/docs/configuracao/referencias/nodes-fluxos-do-bot)
- [Guia geral de fluxos do bot](/docs/configuracao/fluxos-automacoes/guia-geral-de-fluxos-do-bot)
- [Fluxos do bot](/docs/configuracao/fluxos-automacoes/fluxos-do-bot)
- [Cenários comuns de fluxos do bot](/docs/configuracao/fluxos-automacoes/cenarios-comuns-de-fluxos-do-bot)