Nvoip · Base de Conhecimento

Como criar um fluxo de Voicebot com integração com API

Como criar um fluxo de Voicebot com integração com API

Última atualização: 04/08/2026

Este guia cria uma jornada de voz que consulta uma API e usa a resposta no atendimento: Número Virtual → Horário → Voicebot → Integração API → Voicebot ou Fila.

Antes de começar

Tenha a documentação do endpoint, método, autenticação, campos obrigatórios, exemplo de resposta e limites de tempo. Defina também o comportamento quando a API estiver indisponível.

1. Criar a entrada e coletar o dado

  1. Crie o fluxo e selecione o Número Virtual.
  2. Configure Horário normal e especial.
  3. Em HC, adicione um Voicebot com menu ou coleta.
  4. Salve a resposta em uma variável, como numero_protocolo.
  5. Configure erro de digitação, timeout e limite de tentativas.

2. Cadastrar a conexão da API

Na aba Integrações:

  1. clique em Nova integração;
  2. escolha API ou webhook, conforme o recurso;
  3. informe a URL base e a autenticação;
  4. cadastre cabeçalhos fixos quando necessários;
  5. dê um nome que indique sistema e finalidade;
  6. teste e salve.
Área de Integrações
Área de Integrações

Guarde tokens e senhas apenas na conexão protegida. Não escreva segredos no endpoint, corpo adicional, nome do bloco ou mensagem.

3. Configurar a requisição

  1. Adicione Integrações após o Voicebot.
  2. Selecione a conexão e o endpoint.
  3. Confirme o método esperado pela API.
  4. Preencha caminho, parâmetros, cabeçalhos e corpo conforme a documentação.
  5. Insira variáveis com a sintaxe apresentada no editor, como {{numero_protocolo}}.
  6. Use valores fictícios no primeiro teste.
Configuração da conexão e entrada
Configuração da conexão e entrada

Exemplo conceitual de corpo:

Exemplo conceitual: { "protocol": "{{numero_protocolo}}", "channel": "voicebot" }.

O formato real deve seguir a API. Não envie campos extras apenas porque estão disponíveis no fluxo.

4. Variáveis disponíveis na entrada

Além das coletas, a integração pode usar dados de contexto quando disponíveis, como número de origem, número de destino, nome do contato e canal. Confirme o nome exibido no seletor do próprio bloco.

Use variáveis para valores dinâmicos; use a conexão para credenciais e configurações fixas.

5. Mapear a resposta

  1. Execute o teste.
  2. Carregue os campos retornados.
  3. Marque somente os que serão usados.
  4. Salve cada campo com um nome claro.
Retorno da API Variável Uso
customer_name nome_cliente Personalizar a fala.
protocol_status status_protocolo Escolher o destino.
priority prioridade Direcionar a uma fila.
Variáveis de retorno
Variáveis de retorno

6. Configurar sucesso, erro e casos avançados

No modo simples, conecte sucesso ao próximo Voicebot e erro à contingência. No modo avançado, crie regras por valor:

  • status aberto → informar andamento;
  • status concluido → informar conclusão;
  • prioridade alta → Fila especializada;
  • resposta vazia → atendimento humano;
  • erro ou timeout → mensagem curta e Fila geral.
Caminhos da integração
Caminhos da integração

Não repita automaticamente a API muitas vezes. Uma falha persistente pode prolongar a chamada e aumentar a carga no sistema externo.

7. Responder pelo Voicebot

Adicione um Voicebot posterior para usar o retorno. Mantenha a mensagem breve e crie alternativa para campos ausentes.

Exemplo: “O protocolo está com status {{status_protocolo}}. Para falar com um atendente, digite 1.”

8. Testar e publicar

Teste sucesso completo, campo opcional ausente, identificador inexistente, autenticação inválida em ambiente seguro, erro HTTP, resposta inválida e timeout. Confirme os caminhos e publique somente após validar a contingência.

Checklist rápido

  • [ ] Método e endpoint conferidos.
  • [ ] Segredos ficam na conexão.
  • [ ] Corpo usa apenas dados necessários.
  • [ ] Retornos foram mapeados.
  • [ ] Sucesso, erro, vazio e timeout têm destino.
  • [ ] A fala não expõe dados sensíveis.
  • [ ] Chamada real controlada concluída.