Como integrar o Typebot autohospedado ao Connect.ai
O Typebot é um construtor de fluxos conversacionais que roda no seu próprio servidor. Integrado ao Connect.ai, ele assume a conversa no WhatsApp para coletar dados de forma estruturada: formulários, qualificação de leads, orçamentos, agendamentos e cadastros com validação.
Este artigo cobre o caminho completo: criar e publicar o fluxo no Typebot, obter os dois valores que o Connect.ai pede (URL e nome do bot), habilitar a integração no painel e ativá-la no canal ou dentro de uma etapa do Chat Flow.
Dica
Pré-requisitos:
- Typebot autohospedado instalado e acessível por uma URL (ex:
https://bot.seudominio.com), com certificado SSL válido- Acesso ao Painel Admin do Connect.ai (perfil administrador)
- Um canal já conectado no Connect.ai (sessão de WhatsApp, WABA ou Hub NotificaMe)
- O servidor do Connect.ai precisa conseguir alcançar a URL do Typebot pela rede
Como funciona
Quando o Typebot está ativo em um canal, as mensagens que chegam nesse canal são encaminhadas para o fluxo do Typebot, que passa a conduzir a conversa. O Connect.ai mantém o histórico no ticket normalmente e devolve o controle quando o cliente envia a palavra de saída, quando um atendente assume o atendimento ou quando o fluxo termina.
A cada novo contato o Connect.ai abre uma sessão com o Typebot e envia as informações do ticket como variáveis (nome, número, protocolo, canal), que você pode usar dentro do fluxo para personalizar as perguntas.
Atenção
Uma automação por vez no mesmo canal. Se o canal já tiver ChatGPT, Dify, N8N, DialogFlow ou um Chat Flow ativo respondendo, o cliente pode receber mensagens duplicadas. Deixe apenas uma integração respondendo por canal, ou acione o Typebot a partir do Chat Flow (Etapa 5).
Etapa 1: Criar e publicar o fluxo no Typebot
- Acesse o painel do seu Typebot autohospedado no navegador, no endereço configurado na sua instalação (ex:
https://bot.seudominio.com). - Faça login com suas credenciais administrativas.
- Clique em Create a typebot (ou no botão +) para criar um novo fluxo.
- Dê um nome ao fluxo e monte a conversa arrastando os blocos no editor (perguntas, condições, entradas de texto, botões).
- Clique em Publish no canto superior direito.
Importante
Um fluxo não publicado não responde. Toda vez que você editar o fluxo, é preciso clicar em Publish novamente para que a alteração valha no WhatsApp.
Etapa 2: Obter a URL e o nome do bot
O Connect.ai pede dois valores separados, e ambos saem do mesmo lugar: o link de compartilhamento do Typebot.
- Com o fluxo publicado, abra a aba Share no Typebot.
- Copie o link exibido. Ele tem este formato:
https://bot.seudominio.com/meu-formulario-de-orcamento
- Separe o link em duas partes:
| Parte do link | O que é | Campo no Connect.ai |
|---|---|---|
https://bot.seudominio.com | Endereço da sua instalação do Typebot (viewer) | URL do Typebot |
meu-formulario-de-orcamento | Identificador público do fluxo | Nome do Typebot |
Dica
O identificador público é editável na aba Share do Typebot. Use letras minúsculas, números e hífen, sem espaços nem acentos, e evite trocá-lo depois de integrado: se mudar, o Connect.ai deixa de encontrar o fluxo até você atualizar o campo no canal.
Etapa 3: Habilitar o Typebot no Connect.ai
- Acesse o Painel Admin.
- Vá em Configurações e abra a aba Bots e IA.
- No menu lateral, clique em Typebot.
- Ative a chave Habilitar Typebot.
- Se quiser que o Typebot atue automaticamente em todos os novos atendimentos, ative também Habilitar para todos os tickets. Para controlar canal a canal, deixe essa opção desligada.
- Salve.
Dica
Os campos do Typebot só aparecem dentro do canal depois que essa chave é ativada nas configurações gerais.
Etapa 4: Configurar o Typebot no canal
- Acesse Painel Admin e depois Canais.
- Clique no canal que vai usar o bot e abra a edição.
- Localize a seção de integrações e selecione a aba Typebot.
- Preencha os campos:
| Campo | O que preencher | Exemplo |
|---|---|---|
| URL do Typebot | Endereço da instalação, sem barra no final | https://bot.seudominio.com |
| Nome do Typebot | Identificador público do fluxo | meu-formulario-de-orcamento |
| Palavra para desligar | Palavra que o cliente envia para sair do bot e falar com um atendente | atendente |
| Palavra para reiniciar | Palavra que reinicia a sessão do fluxo do zero | reiniciar |
| Mensagem de opção inválida | Texto enviado quando o cliente responde algo fora das opções previstas | Não entendi. Escolha uma das opções acima. |
| Mensagem de escolha de botão | Texto que acompanha os botões enviados pelo fluxo | Selecione uma opção: |
- Ative a chave do Typebot nesse canal e salve.
Atenção
Nas configurações do canal, recomendamos manter ativas as opções Habilitar desligamento automático das integrações externas (o bot para quando um atendente assume o ticket) e Habilitar espera no processamento de mensagens com integrações externas (o sistema processa uma mensagem por vez, evitando que o fluxo se perca quando o cliente envia várias mensagens seguidas).
Etapa 5: Acionar o Typebot dentro do Chat Flow (opcional)
Em vez de deixar o Typebot atendendo tudo, você pode chamá-lo apenas em um ponto do atendimento, por exemplo depois que o cliente escolhe "Pedir orçamento" no menu.
- Acesse Painel Admin, depois Chat Flow, e abra o fluxo desejado.
- Na etapa em que o bot deve assumir, clique em Adicionar interação e escolha Typebot.
- Preencha os mesmos campos da Etapa 4: URL, nome do bot, palavra de saída e palavra de reinício.
- Salve o fluxo.
Importante
Regra de ouro: a interação Typebot precisa ser a última interação da etapa. Qualquer ação depois dela faz o Chat Flow e o Typebot responderem ao mesmo tempo, gerando mensagens duplicadas.
Variáveis que o Connect.ai envia ao Typebot
Crie variáveis com estes nomes dentro do fluxo do Typebot para receber os dados do atendimento e personalizar as perguntas:
| Variável | O que traz |
|---|---|
{{nome}} | Nome do contato |
{{numero}} | Telefone do contato |
{{atendimento}} | Número do ticket |
{{email}} | E-mail do contato, se existir |
{{status}} | Status do ticket |
{{canal}} | Canal pelo qual a mensagem chegou |
{{grupo}} | Indica se o atendimento é em grupo |
{{fullTicket}} | Todas as propriedades do atendimento |
Resumo das Funcionalidades
| Funcionalidade | Onde acessar |
|---|---|
| Criar e publicar o fluxo | Painel do Typebot, aba Share para o link |
| Habilitar a integração | Painel Admin > Configurações > Bots e IA > Typebot |
| Ativar o bot em um canal | Painel Admin > Canais > canal > aba Typebot |
| Acionar o bot em um ponto do atendimento | Painel Admin > Chat Flow > etapa > Adicionar interação > Typebot |
| Consultar as variáveis disponíveis | Painel Admin > Configurações > Variáveis |
Encerramento
Com a integração ativa, o Typebot passa a conduzir a coleta de dados no WhatsApp e devolve o atendimento ao time no momento certo, sem que ninguém precise digitar as mesmas perguntas todos os dias. O histórico continua registrado no ticket do Connect.ai, então o atendente que assume a conversa vê tudo o que o cliente já respondeu.
Atenção
O Typebot é uma ferramenta de terceiros. O Connect.ai oferece a integração nativa, mas a instalação, a manutenção e o funcionamento do Typebot são de responsabilidade de quem hospeda. Consulte a política de suporte técnico.
Possíveis Erros e Soluções
A aba Typebot não aparece nas configurações do canal
Causa: a integração não foi habilitada nas configurações gerais. Solução: ative Habilitar Typebot em Painel Admin > Configurações > Bots e IA > Typebot, salve e recarregue a página do canal.
O bot não responde nenhuma mensagem
Causa: fluxo não publicado, nome do bot incorreto ou URL inacessível pelo servidor do Connect.ai. Solução: confirme que o fluxo está publicado (Publish), abra o link de compartilhamento no navegador para ver se o fluxo carrega e revise os campos URL do Typebot (sem barra no final) e Nome do Typebot (apenas o identificador, sem o domínio).
O cliente recebe mensagens duplicadas
Causa: mais de uma automação ativa no mesmo canal (Chat Flow, ChatGPT, Dify ou N8N respondendo em paralelo). Solução: deixe apenas uma automação respondendo por canal. Se usar o Chat Flow, coloque a interação Typebot como última interação da etapa.
O bot continua respondendo mesmo com o atendente na conversa
Causa: desligamento automático das integrações externas desativado no canal. Solução: ative Habilitar desligamento automático das integrações externas nas configurações do canal, ou oriente o cliente a enviar a palavra de saída configurada.
O fluxo se perde quando o cliente manda várias mensagens seguidas
Causa: as mensagens chegam ao Typebot fora de ordem, antes que a anterior seja respondida. Solução: ative Habilitar espera no processamento de mensagens com integrações externas nas configurações do canal.
O bot reinicia do começo em toda mensagem
Causa: a palavra digitada pelo cliente coincide com a palavra para reiniciar configurada. Solução: troque a palavra de reinício por um termo que não apareça em conversas normais, como reiniciar-bot.
As variáveis chegam vazias no fluxo
Causa: o nome da variável no Typebot está diferente do enviado pelo Connect.ai. Solução: crie no Typebot variáveis com exatamente os mesmos nomes da tabela acima (nome, numero, atendimento), respeitando minúsculas e sem acento.