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

Ampliar

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

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:

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

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

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

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
• Telefonia
• Cadastro de URA
• Vínculo do fluxo de telefonia no número de entrada