Como usar Integrações e variáveis no Voicebot e Chatbot
Como usar Integrações e variáveis no fluxo de Voicebot e Chatbot
Última atualização: 04/08/2026
O bloco Integrações conecta o Fluxo a APIs, webhooks e bancos de dados. As variáveis levam informações do contato para a integração e trazem o retorno para Voicebots, Chatbots, condições e filas.
1. Entender conexão, requisição e variável
- Conexão: guarda endereço e autenticação reutilizáveis.
- Endpoint ou operação: define a ação executada.
- Variável de entrada: fornece um valor dinâmico à requisição.
- Variável de retorno: salva um campo recebido para etapas posteriores.
- Caminho: determina o próximo bloco em sucesso, erro ou caso específico.
2. Criar a conexão reutilizável
- Abra a aba Integrações do Fluxo.
- Clique em Nova integração.
- Escolha API, webhook ou banco, conforme o objetivo.
- Informe os dados fixos e a autenticação.
- Teste a conexão.
- Salve com nome descritivo.
Credenciais devem ficar na conexão. Nunca crie uma variável com token, senha ou chave secreta para exibi-la no fluxo.
3. Adicionar o bloco ao fluxo
- Adicione Integrações no ponto em que os dados de entrada já existirem.
- Selecione a conexão.
- Selecione endpoint ou operação.
- Preencha parâmetros e corpo adicional.
- Use o seletor de variáveis para evitar erros de digitação.
4. Variáveis de contexto
Conforme o canal, podem estar disponíveis valores como:
| Variável de contexto | Conteúdo esperado |
|---|---|
contact_name |
Nome conhecido do contato. |
contact_number |
Número do contato. |
contact_email |
E-mail conhecido. |
contact_company |
Empresa vinculada. |
contact_channel_id |
Identificador do contato no canal. |
contact_profile_name |
Nome do perfil. |
contact_username |
Usuário do canal. |
origin_number |
Número de origem da interação. |
destination_number |
Número ou destino que recebeu o contato. |
channel |
Canal da conversa ou chamada. |
Uma variável pode não existir ou vir vazia em determinados canais. Configure a integração para aceitar ausência quando o campo não for obrigatório.
5. Variáveis coletadas no fluxo
Voicebot e Chatbot podem criar variáveis por coleta. Use nomes que descrevam o conteúdo:
codigo_cliente;email_cliente;motivo_contato;numero_protocolo.
Evite nomes genéricos como valor1. Não reutilize o mesmo nome para documento e protocolo.
6. Inserir variáveis na requisição
Use a sintaxe exibida pelo editor, normalmente {{nome_da_variavel}}.
Exemplo conceitual de API:
Exemplo conceitual: { "customer": "{{codigo_cliente}}", "source": "{{channel}}" }.
Em banco de dados, associe a variável a um parâmetro. Não concatene diretamente a resposta do cliente em comandos.
7. Criar variáveis de retorno
- Execute uma requisição de teste.
- Clique para carregar o retorno.
- Localize os campos necessários.
- Em Guardar como, defina o nome da variável.
- Salve a integração.
Exemplo:
| Campo recebido | Guardar como | Uso posterior |
|---|---|---|
contact_id |
id_contato |
Segunda integração. |
name |
nome_cliente |
Mensagem personalizada. |
status |
status_cliente |
Condição de destino. |
8. Escopo e ordem
A ordem importa:
- o canal fornece variáveis de contexto;
- o Voicebot ou Chatbot coleta novos valores;
- a integração usa essas entradas;
- a integração cria variáveis de retorno;
- blocos posteriores usam o retorno.
Se um bloco tentar usar {{nome_cliente}} antes da integração que cria esse valor, a variável estará vazia.
9. Sucesso, erro e casos avançados
No modo simples, conecte as saídas de sucesso e erro. No modo avançado, crie casos por valor retornado.
Mantenha um caminho padrão para valor desconhecido. Casos específicos não substituem a contingência de erro ou timeout.
10. Uso no Voicebot e Chatbot
- Voicebot: personalizar fala, escolher menu ou fila.
- Chatbot: confirmar protocolo, preencher mensagem ou selecionar atendimento.
- Nova integração: enviar um identificador retornado pela primeira.
- Fila: escolher equipe ou informar contexto ao agente, conforme os recursos disponíveis.
Não exponha dados internos apenas porque foram retornados pelo sistema.
11. Diagnóstico
Se a variável não aparece:
- confirme que a integração foi executada;
- refaça o teste e carregue o retorno;
- confira o caminho exato do campo;
- confira Guardar como;
- valide se o bloco que usa a variável vem depois;
- teste retorno vazio e tipo diferente;
- verifique se o fluxo publicado contém a última alteração.
Checklist rápido
- [ ] Credenciais somente na conexão.
- [ ] Entradas existem antes da integração.
- [ ] Retorno foi testado e mapeado.
- [ ] Nomes de variáveis são claros.
- [ ] Campo vazio tem tratamento.
- [ ] Sucesso, erro, timeout e padrão possuem destino.
- [ ] Nenhum dado sensível é exibido indevidamente.