Nvoip · Base de Conhecimento

Como criar um fluxo de Voicebot com integração com banco de dados

Como criar um fluxo de Voicebot com integração com banco de dados

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

Este guia mostra uma jornada de voz que consulta um banco de dados antes de decidir o atendimento: Número Virtual → Horário → Voicebot → Integração com banco → Voicebot ou Fila.

Use esse modelo para consultar situação cadastral, localizar contrato, identificar segmento ou recuperar outra informação necessária ao roteamento.

Antes de começar

Solicite ao responsável técnico:

  • conexão de banco já cadastrada ou dados para cadastrá-la com segurança;
  • operação permitida e campos que podem ser consultados;
  • variável usada como chave, como documento ou código do cliente;
  • exemplo de retorno de sucesso, registro não encontrado e erro;
  • destino para cada resultado.

Use uma credencial de acesso mínimo. Não coloque senha em mensagens, nomes de blocos ou variáveis visíveis ao cliente.

1. Criar a jornada de voz

  1. Crie o fluxo.
  2. Adicione Número Virtual.
  3. Adicione e configure Horário.
  4. Conecte HC ao Voicebot de identificação.
  5. Configure FHC com aviso e destino próprio.

2. Coletar a chave de consulta

No Voicebot:

  1. escolha Coleta de dados;
  2. peça somente a informação necessária;
  3. defina quantidade mínima e máxima de dígitos;
  4. configure timeout, resposta inválida e limite de tentativas;
  5. salve o valor em uma variável clara, como codigo_cliente.

Repita o valor somente se isso não expuser informação sensível. Para números longos, ofereça uma forma de corrigir a digitação antes da consulta.

Configuração do Voicebot
Configuração do Voicebot

3. Cadastrar a conexão de banco

Na aba Integrações:

  1. clique em Nova integração;
  2. escolha o tipo de banco disponível para a conta;
  3. informe host, porta, base e credencial no cadastro seguro;
  4. use um nome descritivo, como Banco clientes - consulta;
  5. teste a conexão;
  6. salve somente depois da validação.
Área de conexões reutilizáveis
Área de conexões reutilizáveis

A conexão fica vinculada à conta e pode ser reutilizada. O fluxo deve guardar a referência, não copiar credenciais.

4. Configurar o bloco Integrações

  1. Adicione Integrações depois da coleta.
  2. Selecione a conexão de banco.
  3. Escolha a operação ou consulta previamente autorizada.
  4. Associe {{codigo_cliente}} ao parâmetro de entrada esperado.
  5. Não monte comandos com concatenação livre de texto do cliente; use parâmetros.
  6. Execute um teste com dado fictício conhecido.
Conexão e variáveis de entrada
Conexão e variáveis de entrada

5. Mapear o retorno

Depois do teste, carregue os campos retornados e crie variáveis com nomes compreensíveis:

Campo retornado Variável no fluxo Uso
customer_name nome_cliente Saudação do Voicebot.
customer_status status_cliente Escolha do destino.
customer_segment segmento_cliente Fila especializada.
Mapeamento das variáveis de retorno
Mapeamento das variáveis de retorno

As variáveis passam a existir depois que a integração é executada. Um bloco anterior não pode usar um valor que ainda não foi criado.

6. Criar os caminhos

No modo simples, configure:

  • Requisição executada com sucesso → avaliar o retorno;
  • Requisição retornou erro → mensagem de indisponibilidade e Fila geral.

No modo avançado, crie casos como:

  • status_cliente=ativo → menu principal;
  • status_cliente=pendente → Fila Financeiro;
  • registro não encontrado → nova tentativa ou atendimento humano;
  • erro/timeout → contingência sem depender do banco.
Caminhos de sucesso e erro
Caminhos de sucesso e erro

7. Usar as variáveis no Voicebot

Em um Voicebot posterior, use a variável conforme o recurso permitir, por exemplo: “Olá, {{nome_cliente}}. Identificamos seu cadastro.”

Sempre crie uma frase que continue fazendo sentido se um campo opcional vier vazio. Não fale ao telefone informações que possam expor o cliente a terceiros.

8. Testar

Valide:

  1. chave válida com registro;
  2. chave válida sem registro;
  3. formato inválido;
  4. retorno sem campo opcional;
  5. banco indisponível;
  6. timeout;
  7. cada valor usado no roteamento;
  8. fila de contingência.

Use dados fictícios ou uma base de teste. Nunca altere registros reais durante uma consulta de validação.

9. Publicar

Salve, corrija pendências, teste por telefone, ative e publique. Depois da publicação, faça uma chamada controlada e confirme nos registros técnicos que a consulta ocorreu apenas uma vez.

Checklist rápido

  • [ ] Credencial de acesso mínimo.
  • [ ] Entrada parametrizada.
  • [ ] Variáveis mapeadas após teste.
  • [ ] Registro inexistente tratado.
  • [ ] Erro e timeout têm contingência.
  • [ ] Nenhum dado sensível é falado indevidamente.
  • [ ] Todos os resultados foram testados.