# 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-09-04T17:55:41.677Z

## Página

- Título: Requisição HTTP Personalizada no fluxo de voz
- URL humana: https://agilize.app/docs/configuracao/referencias/nodes-fluxos-de-voz/requisicao-http-personalizada
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Configure uma requisição HTTP durante a chamada e direcione o fluxo de voz conforme a resposta.

## Seções

- Quando usar
- Onde configurar
- Visão da configuração
- Campos de configuração
- Entradas e saídas
- Usar variáveis da chamada
- Enviar o contexto completo da chamada
- Salvar e reutilizar a resposta

## Conteúdo da página

# Requisição HTTP Personalizada no fluxo de voz

O node **Requisição HTTP Personalizada** consulta ou envia dados para uma API durante a chamada. Ele aguarda a resposta antes de continuar e permite escolher o próximo caminho pelo status HTTP ou por uma condição aplicada ao conteúdo retornado.

## Quando usar

- consultar cadastro, disponibilidade, pedido ou protocolo em uma API própria;
- enviar dados coletados durante a chamada;
- usar o retorno de uma integração nos próximos nodes;
- separar sucesso, resposta rejeitada e falha técnica em caminhos diferentes;
- configurar a requisição inteira no próprio fluxo, sem cadastrar antes uma operação de integração.

Evite este node quando o envio não deve interromper a chamada. Nesse caso, use **Envio de Webhook HTTP**, que dispara o POST de forma assíncrona e segue o fluxo sem aguardar o retorno.

## Onde configurar

Acesse :ScreenEntry{href="https://my.agilize.app/voice/flow" label="Fluxos Avançados na plataforma"}. Pela interface, abra o módulo **Voz**, selecione **Configurações** e, na árvore **Telefonia e Voz**, escolha **Fluxos Avançados**.

Abra ou crie um fluxo. No editor, localize o grupo **Dados e Integrações**, arraste **Requisição HTTP Personalizada** para o canvas e conecte sua entrada e suas três saídas.

## Visão da configuração

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

Na imagem, o node usa `POST` e o body **Contexto**. Nesse modo, a Agilize monta o JSON no momento da chamada com `call`, `flow` e `vars`.

## Campos de configuração

| Campo | Como usar |
| --- | --- |
| Nome da requisição | Identificação opcional exibida no node, como `Consultar disponibilidade`. |
| Método | Escolha `GET`, `POST`, `PUT`, `PATCH`, `DELETE` ou `HEAD`. |
| URL | Informe um endereço HTTP ou HTTPS. Campos compatíveis aceitam variáveis no formato `{{variável}}`. |
| Parâmetros | Pares de chave e valor adicionados à query string com codificação automática. |
| Autenticação | Sem autenticação, Bearer, Basic ou API Key enviada em header ou query. |
| Headers | Cabeçalhos adicionais da requisição. Valores sensíveis podem ser protegidos. |
| Body | Vazio, JSON, URL encoded, Raw ou Contexto. Disponível para `POST`, `PUT`, `PATCH` e `DELETE`. |
| Status HTTP aceitos | Faixas separadas por vírgula que definem sucesso. O padrão é `200-299`. |
| Variável de saída | Nome da variável que receberá somente o body retornado. |
| Validar conteúdo da resposta | Condição opcional aplicada a um caminho do body. |
| Timeout | Tempo máximo de espera entre 1 e 30 segundos. O padrão é 10 segundos. |
| Redirecionamentos | Quando ativo, segue até três redirecionamentos. |

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

## Entradas e saídas

O node recebe uma entrada e oferece três saídas:

| Saída | Quando é usada |
| --- | --- |
| Sucesso | O endpoint respondeu e o status HTTP e a condição opcional foram aceitos. |
| Resposta não aceita | O endpoint respondeu, mas o status ou a condição aplicada ao body não passou na regra. |
| Erro técnico | Houve URL inválida, timeout, erro de rede ou configuração incorreta. |

Conecte as três saídas. Isso evita que a chamada fique sem um tratamento previsto quando a API rejeitar a solicitação ou estiver indisponível.

## Usar variáveis da chamada

Use **Inserir variável** nos campos que exibem essa ação. O seletor reúne dados da telefonia e variáveis produzidas pelos nodes anteriores do mesmo fluxo.

| Variável | Conteúdo |
| --- | --- |
| `{{callerid}}` | Número de origem da chamada. |
| `{{uniqueid}}` | Identificador único da chamada. |
| `{{channel}}` | Canal atual da ligação. |
| `{{context}}` | Contexto atual do dialplan. |
| `{{extension}}` | Extensão atual. |
| `{{call}}` | Objeto com os dados atuais da chamada. |
| `{{flow}}` | Identificação do fluxo de voz em execução. |

Variáveis criadas por nodes anteriores também ficam disponíveis. Por exemplo, se **Solicitar Informação** salvar o CPF em `cpf`, use `{{cpf}}` ou um subcampo com notação de ponto quando o valor for um objeto.

## Enviar o contexto completo da chamada

Para enviar o estado atual sem montar o JSON manualmente, abra **Body** e escolha **Contexto**. O node gera um `application/json` com esta estrutura:

```json
{
  "call": {},
  "flow": {},
  "vars": {}
}
```

- `call` contém dados atuais da chamada, como identificadores, número de origem, canal, contexto, extensão e variáveis do canal;
- `flow` identifica o fluxo telefônico em execução;
- `vars` contém as variáveis acumuladas até aquele ponto, inclusive respostas de outros nodes.

Use **Contexto** apenas quando a API realmente precisar desse conjunto. Para enviar poucos campos, prefira **JSON** ou **Raw** e insira somente as variáveis necessárias.

## Salvar e reutilizar a resposta

Preencha **Variável de saída** para disponibilizar o body retornado aos próximos nodes. Se o nome informado for `respostaApi`, por exemplo, o conteúdo poderá ser usado como `{{respostaApi}}` ou por caminhos como `{{respostaApi.cliente.id}}`.

Após uma resposta HTTP, o node também mantém:

| Variável | Conteúdo |
| --- | --- |
| `NodeHttpRequestLastRes` | Último body recebido. |
| `NodeHttpRequestLastStatus` | Último status HTTP recebido. |

Essas variáveis podem ser selecionadas por nodes posteriores no mesmo fluxo.

## Configurar a regra de sucesso

Por padrão, respostas de `200` a `299` seguem por **Sucesso**. Você pode aceitar outras faixas separadas por vírgula e ativar **Validar conteúdo da resposta** para conferir também um caminho do body, como `data.disponivel`.

As condições disponíveis verificam se um campo existe, não está vazio, contém uma lista com itens, é igual ou é diferente do valor esperado. O status e a condição precisam ser aceitos; caso contrário, o fluxo segue por **Resposta não aceita**.

## Exemplo prático

Para consultar disponibilidade antes de enviar a chamada a uma fila:

1. adicione **Requisição HTTP Personalizada** depois do node que coletou a informação necessária;
2. use `POST` e informe uma URL pública HTTPS;
3. escolha **JSON** e envie apenas os dados necessários ou use **Contexto** quando a API precisar de todo o estado da chamada;
4. mantenha `200-299` como status aceitos e valide `data.disponivel`, se o endpoint retornar esse campo;
5. conecte **Sucesso** à fila adequada;
6. conecte **Resposta não aceita** a uma mensagem ou rota alternativa;
7. conecte **Erro técnico** a um fallback seguro, como uma fila geral.

## Escolher o node de integração correto

| Necessidade | Node recomendado |
| --- | --- |
| Configurar método, URL, autenticação, headers, body e regra de resposta no fluxo | **Requisição HTTP Personalizada** |
| Executar um método de uma plataforma de integração já cadastrada | **Chamada API Externa** |
| Apenas notificar uma URL sem aguardar a resposta | **Envio de Webhook HTTP** |

## Segurança e cuidados

- Prefira HTTPS. A interface avisa quando a URL usa HTTP.
- Endereços locais e redes privadas são bloqueados.
- Proteja tokens, senhas, API Keys e valores secretos de parâmetros, headers ou body URL encoded.
- Credenciais protegidas são armazenadas com segurança ao salvar o fluxo e aparecem mascaradas no teste.
- Envie apenas os dados necessários, principalmente ao usar o body **Contexto**.
- Considere o tempo de espera na experiência da chamada. Configure um timeout compatível e mantenha uma rota de erro técnico.

## Como testar

1. Informe método e URL e clique em **Testar**.
2. Preencha o modal com dados fictícios para as variáveis usadas.
3. Se o body for **Contexto**, revise o exemplo de `call`, `flow` e `vars` antes de executar.
4. Confira status, tempo, body, headers e requisição resolvida.
5. Teste os cenários de sucesso, resposta não aceita e erro técnico.
6. Depois, faça uma chamada controlada para validar a jornada completa antes de usar o fluxo em produção.

O teste exige perfil de administrador, não salva o fluxo e não persiste os dados customizados informados no modal.

## Guias relacionados

- [Nodes de fluxos de voz](/docs/configuracao/referencias/nodes-fluxos-de-voz)
- [Telefonia](/docs/configuracao/telefonia)
- [Cadastro de URA](/docs/configuracao/telefonia/cadastro-de-ura)
- [Vínculo do fluxo de telefonia no número de entrada](/docs/configuracao/telefonia/vinculo-fluxo-telefonia-numero-entrada)