Nvoip · Base de Conhecimento

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

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

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

Este guia mostra como um Chatbot envia dados a uma API, recebe uma resposta e segue para uma mensagem, condição ou Fila de Mensageria.

Antes de começar

Tenha a documentação da API, conexão/autenticação, método, endpoint, campos obrigatórios, exemplo de resposta e regra de contingência. Use um ambiente de teste quando a requisição puder criar ou alterar dados.

1. Criar o canal e a coleta

  1. Crie o fluxo e adicione o canal de entrada.
  2. Configure Horário.
  3. Adicione um Chatbot com saudação e motivo da solicitação.
  4. Colete somente os campos exigidos.
  5. Salve cada resposta em variável clara, como email_cliente e assunto.

2. Cadastrar a conexão da API

Na aba Integrações:

  1. clique em Nova integração;
  2. escolha API ou webhook;
  3. informe URL base, autenticação e cabeçalhos fixos;
  4. teste a conexão;
  5. salve com nome que identifique o sistema.
Área de Integrações
Área de Integrações

Tokens e senhas devem permanecer na conexão protegida. Não os copie para o conteúdo do Chatbot.

3. Configurar a requisição

  1. Adicione Integrações após as coletas.
  2. Selecione a conexão e o endpoint.
  3. Confira método, parâmetros e corpo.
  4. Insira as variáveis pelo seletor do editor.
  5. Faça um teste com dados fictícios.
Conexão e variáveis de entrada
Conexão e variáveis de entrada

Exemplo conceitual:

Exemplo conceitual: { "email": "{{email_cliente}}", "subject": "{{assunto}}", "channel": "{{channel}}" }.

Use somente o formato previsto pela API. Diferencie campos fixos, configurados no endpoint, de valores variáveis vindos da conversa.

4. Mapear a resposta

Depois do teste:

  1. carregue os campos retornados;
  2. selecione os necessários;
  3. use nomes simples, sem espaços;
  4. evite sobrescrever uma variável com significado diferente.
Variáveis de retorno
Variáveis de retorno

Exemplo:

Retorno Variável Uso
ticket_id protocolo Confirmar a solicitação.
status status_api Escolher o caminho.
queue fila_sugerida Direcionar atendimento.

5. Configurar os caminhos

No modo simples, conecte sucesso à confirmação e erro à contingência. No modo avançado, avalie valores retornados.

Caminhos de sucesso e erro
Caminhos de sucesso e erro

Exemplo:

  • sucesso com ticket_id → “Sua solicitação foi criada com o protocolo {{protocolo}}.”;
  • sucesso sem protocolo → Fila humana para conferência;
  • validação recusada → pedir correção do campo;
  • erro/timeout → informar indisponibilidade e oferecer atendimento humano.

6. Evitar envios duplicados

Se a API cria registros, não retorne automaticamente ao mesmo bloco após erro ou resposta livre. Um clique repetido ou uma conexão circular pode criar solicitações duplicadas. Prefira confirmação, identificador de idempotência quando suportado e uma única tentativa automática.

7. Testar

Valide:

  • sucesso com todos os campos;
  • campo opcional ausente;
  • erro de validação;
  • autenticação e permissão em ambiente seguro;
  • resposta inválida;
  • timeout;
  • clique ou mensagem repetida;
  • fila de contingência.

8. Publicar

Salve, corrija pendências, teste no canal real, ative e publique. Confira no sistema externo se houve apenas o efeito esperado.

Checklist rápido

  • [ ] Método e endpoint corretos.
  • [ ] Segredos ficam na conexão.
  • [ ] Variáveis de entrada revisadas.
  • [ ] Retornos necessários mapeados.
  • [ ] Duplicidade foi considerada.
  • [ ] Erro e timeout possuem contingência.
  • [ ] Teste no sistema externo concluído.