> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/avancado-recursos-tecnicos/integracoes-terceiras/typebot-autohospedado.md). # Typebot autohospedado Como criar o fluxo no Typebot autohospedado, obter a URL e o nome do bot e conectar tudo ao Z-PRO, no canal ou dentro do Chat Flow ## Como integrar o Typebot autohospedado ao Z-PRO O Typebot é um construtor de fluxos conversacionais que roda no seu próprio servidor. Integrado ao Z-PRO, 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 Z-PRO 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. {% hint style="info" %} **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 Z-PRO (perfil administrador) * Um canal já conectado no Z-PRO (sessão de WhatsApp, WABA ou Hub NotificaMe) * O servidor do Z-PRO precisa conseguir alcançar a URL do Typebot pela rede {% endhint %} *** ### 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 Z-PRO 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 Z-PRO 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. {% hint style="warning" %} **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). {% endhint %} *** ### Etapa 1: Criar e publicar o fluxo no Typebot 1. Acesse o painel do seu Typebot autohospedado no navegador, no endereço configurado na sua instalação (ex: `https://bot.seudominio.com`). 2. Faça login com suas credenciais administrativas. 3. Clique em **Create a typebot** (ou no botão **+**) para criar um novo fluxo. 4. Dê um nome ao fluxo e monte a conversa arrastando os blocos no editor (perguntas, condições, entradas de texto, botões). 5. Clique em **Publish** no canto superior direito. {% hint style="danger" %} **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. {% endhint %} *** ### Etapa 2: Obter a URL e o nome do bot O Z-PRO pede dois valores separados, e ambos saem do mesmo lugar: o link de compartilhamento do Typebot. 1. Com o fluxo publicado, abra a aba **Share** no Typebot. 2. Copie o link exibido. Ele tem este formato: ``` https://bot.seudominio.com/meu-formulario-de-orcamento ``` 3. Separe o link em duas partes: | Parte do link | O que é | Campo no Z-PRO | | ----------------------------- | ---------------------------------------------- | ------------------- | | `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** | {% hint style="info" %} 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 Z-PRO deixa de encontrar o fluxo até você atualizar o campo no canal. {% endhint %} *** ### Etapa 3: Habilitar o Typebot no Z-PRO 1. Acesse o **Painel Admin**. 2. Vá em **Configurações** e abra a aba **Bots e IA**. 3. No menu lateral, clique em **Typebot**. 4. Ative a chave **Habilitar Typebot**. 5. 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. 6. Salve. {% hint style="info" %} Os campos do Typebot **só aparecem dentro do canal** depois que essa chave é ativada nas configurações gerais. {% endhint %} *** ### Etapa 4: Configurar o Typebot no canal 1. Acesse **Painel Admin** e depois **Canais**. 2. Clique no canal que vai usar o bot e abra a edição. 3. Localize a seção de integrações e selecione a aba **Typebot**. 4. 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:` | 5. Ative a chave do Typebot nesse canal e salve. {% hint style="warning" %} 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). {% endhint %} *** ### 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. 1. Acesse **Painel Admin**, depois **Chat Flow**, e abra o fluxo desejado. 2. Na etapa em que o bot deve assumir, clique em **Adicionar interação** e escolha **Typebot**. 3. Preencha os mesmos campos da Etapa 4: URL, nome do bot, palavra de saída e palavra de reinício. 4. Salve o fluxo. {% hint style="danger" %} **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. {% endhint %} *** ### Variáveis que o Z-PRO 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 Z-PRO, então o atendente que assume a conversa vê tudo o que o cliente já respondeu. {% hint style="warning" %} O Typebot é uma ferramenta de terceiros. O Z-PRO 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. {% endhint %} *** ### 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 Z-PRO. **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 Z-PRO. **Solução:** crie no Typebot variáveis com exatamente os mesmos nomes da tabela acima (`nome`, `numero`, `atendimento`), respeitando minúsculas e sem acento. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://ajuda.zdg.com.br/avancado-recursos-tecnicos/integracoes-terceiras/typebot-autohospedado.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.