Chatbot WhatsApp Typebot Self-Hosted: Tutorial Completo

Introdução à Automação WhatsApp Self-Hosted com Typebot e IA

A automação de comunicação via WhatsApp deixou de ser apenas uma vantagem competitiva para se tornar uma necessidade operacional crítica. Para desenvolvedores, sysadmins e profissionais de TI, a capacidade de integrar chatbots inteligentes diretamente no fluxo de trabalho da empresa exige controle total sobre os dados, latência reduzida e custos previsíveis. Neste tutorial técnico, exploraremos como orquestrar um ecossistema robusto utilizando Typebot como interface visual de conversação, combinado com agentes de IA Generativa para respostas contextuais, tudo rodando em infraestrutura self-hosted.

A abordagem aqui não envolve APIs pagas por mensagem (como a oficial do Meta), mas sim soluções baseadas em bibliotecas como Baileys ou wrappers de protocolo QRCode. Isso permite que você mantenha o controle absoluto da lógica de negócio, utilize webhooks para integrar com sistemas externos e realize disparos em massa personalizados sem as restrições rígidas das janelas de tempo da API oficial. Prepararemos um ambiente Dockerizado para garantir portabilidade e facilidade de manutenção.

Arquitetura do Sistema Proposto

Antes de iniciar a implementação, é crucial entender como os componentes se comunicam. Nossa arquitetura será composta por três pilares principais:

Typebot (Engine): Responsável por gerenciar o fluxo lógico do bot (nós de texto, entrada de usuário, condições). Ele será hospedado localmente ou em sua VPS.
Gateway WhatsApp (Baileys/WPPConnect): Um serviço intermediário que mantém a sessão ativa no WhatsApp Web e expõe uma API REST ou WebSocket para receber e enviar mensagens.
Integração de IA: Um endpoint simples (pode ser feito em Node.js, Python ou Go) que recebe o texto do usuário, processa via LLM (como Llama 3, Mistral ou GPT-4 via API local/remote) e retorna a resposta formatada para o Typebot.

Esta separação de responsabilidades permite que você substitua o motor de IA ou o gateway WhatsApp sem derrubar todo o sistema. Para fins didáticos, utilizaremos Docker Compose como ferramenta de orquestração, pois facilita a gestão de variáveis de ambiente e volumes de dados.

Passo 1: Preparando o Ambiente Docker

O primeiro passo é garantir que seu servidor (Linux, preferencialmente Ubuntu ou Debian) tenha o Docker e o Docker Compose instalados. Verifique as versões com os comandos abaixo:

docker --version
docker compose version

Caso não possua os pacotes, atualize o sistema e instale-os via repositório oficial ou package manager nativo (apt/yum). Para ambientes de produção, recomenda-se o uso de Docker Compose V2 integrado ao binário do Docker.

Crie um diretório dedicado para o projeto:

mkdir -p ~/typebot-whatsapp-ai && cd ~/typebot-whatsapp-ai

Passo 2: Configurando o Typebot

O Typebot requer um banco de dados PostgreSQL para persistir os fluxos e variáveis de sessão. Vamos definir as configurações iniciais no arquivo docker-compose.yml.

version: '3.8'

services:
  typebot-web:
    image: baptisteArno/typebot-web:latest
    container_name: typebot_web
    restart: unless-stopped
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=postgresql://typebot:password@db:5432/typebot
      - NEXT_PUBLIC_BASE_URL=http://localhost:4000
      - JWT_SECRET=seu_jwt_secret_super_secreto_muito_longo_aqui
    depends_on:
      - db

  typebot-worker:
    image: baptisteArno/typebot-worker:latest
    container_name: typebot_worker
    restart: unless-stopped
    environment:
      - DATABASE_URL=postgresql://typebot:password@db:5432/typebot
      - NEXT_PUBLIC_BASE_URL=http://localhost:4000
      - JWT_SECRET=seu_jwt_secret_super_secreto_muito_longo_aqui
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: typebot_db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=typebot
      - POSTGRES_USER=typebot
      - POSTGRES_PASSWORD=password
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Neste arquivo, expomos a porta 4000 para acesso à interface web. É altamente recomendável alterar o JWT_SECRET e a senha do banco de dados antes de subir os containers. Inicie os serviços com:

docker compose up -d

Acesse http://localhost:4000 (ou o IP da sua VPS) para criar a conta admin do Typebot. Após o login, você estará pronto para desenhar seus fluxos de conversação.

Passo 3: Criando o Fluxo no Typebot com IA

Dentro do editor do Typebot, crie um novo bot. A chave para a inteligência da conversa está na integração com sua API de IA. Utilize o nó "External API" (ou "Webhook") do Typebot.

Crie um nó de texto inicial: "Olá! Como posso ajudar você hoje?"
Adicione um nó de entrada de texto para capturar a dúvida do usuário.
Conecte este nó ao nó "External API".

Nas configurações do nó "External API", defina:

Method: POST
URL: http://seu-servidor-ia:8080/chat (endpoint que criaremos no próximo passo)
Body: Envie o texto capturado do usuário. Exemplo em JSON: {"message": "{{userInput}}"}
Response Mapping: Mapeie a resposta da API para uma variável, ex: {{aiResponse}}.

Por fim, adicione um nó de texto que utiliza a variável {{aiResponse}} para enviar a mensagem ao usuário. Isso cria o ciclo de interação inteligente.

Passo 4: Desenvolvendo o Gateway WhatsApp e API de IA

Agora precisamos conectar o Typebot ao mundo real via WhatsApp. Para isso, utilizaremos uma abordagem híbrida: um script Node.js que utiliza a biblioteca Baileys (ou similar) para manter a sessão WhatsApp e expor uma API REST simples.

Crie um novo projeto Node.js:

mkdir whatsapp-gateway && cd whatsapp-gateway
npm init -y
npm install express baileys qrcode-terminal axios

O código abaixo (server.js) demonstra a estrutura básica. Ele inicia o scanner QRCode e escuta eventos de mensagem recebida, encaminhando-os para o webhook do Typebot.

const { default: makeWASocket, useMultiFileAuthState, DisconnectReason } = require('@whiskeysockets/baileys');
const express = require('express');
const fs = require('fs');
const path = require('path');

const app = express();
app.use(express.json());

// Configuração de autenticação multi-arquivo
const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys');
const sock = makeWASocket({ auth: state });

// Webhook do Typebot (ajuste a URL conforme seu ambiente)
const TYPEBOT_WEBHOOK_URL = 'http://localhost:4000/api/v1/bot/SEU_BOT_ID/send';

sock.ev.on('messages.upsert', async ({ messages }) => {
    const msg = messages[0];
    if (!msg.message || msg.key.fromMe) return;

    const text = msg.message.conversation || msg.message.extendedTextMessage?.text || '';
    const sender = msg.key.remoteJid;

    console.log(`Mensagem recebida de ${sender}: ${text}`);

    // Aqui você pode processar a IA localmente ou enviar para o Typebot
    // Exemplo: Envia para o Typebot via API interna se estiver usando fluxo complexo
    
    // Resposta simples direta (exemplo básico)
    const responseText = `Você disse: ${text}. Estou conectado!`;
    
    await sock.sendMessage(sender, { text: responseText });
});

// Salvar credenciais ao atualizar
sock.ev.on('creds.update', saveCreds);

// Endpoint para disparos em massa ou gestão (segure com autenticação!)
app.post('/broadcast', async (req, res) => {
    const { message, contacts } = req.body;
    // Lógica de loop para enviar mensagens a múltiplos contatos
    for (const contact of contacts) {
        try {
            await sock.sendMessage(contact, { text: message });
        } catch (e) {
            console.error(`Erro ao enviar para ${contact}:`, e);
        }
    }
    res.json({ status: 'completed' });
});

sock.ev.on('connection.update', async (update) => {
    const { connection, lastDisconnect } = update;
    if (connection === 'close') {
        const shouldReconnect = lastDisconnect.error?.output?.statusCode !== DisconnectReason.loggedOut;
        if (shouldReconnect) sock.connect();
    } else if (connection === 'open') {
        console.log('Conectado com sucesso!');
    }
});

sock.ev.on('creds.update', saveCreds);

app.listen(8080, () => console.log('Gateway rodando na porta 8080'));

Nota Importante: A biblioteca Baileys é a base de muitas soluções open-source. Certifique-se de manter suas credenciais em auth_info_baileys seguras, pois elas permitem acesso total à conta do WhatsApp. Para produção, considere usar volumes Docker para persistir esses dados entre reinicializações.

Passo 5: Integrando com Chatwoot (Opcional)

Se você precisa de uma visão unificada de todos os canais (WhatsApp, Webchat, Email), integrar com Chatwoot é uma excelente estratégia. O Chatwoot atua como um CRM e central de atendimento.

Instale o Chatwoot via Docker ou instale a versão cloud.
No painel do Chatwoot, adicione o canal WhatsApp (utilizando o provider "Generic" ou integrações baseadas em QRCode).
Configure o webhook de envio no Chatwoot para apontar para seu serviço Baileys.
No Typebot, utilize a API do Chatwoot para buscar histórico do cliente e enriquecer as respostas da IA.

Essa integração permite que sua IA tenha contexto: "O cliente X já teve o pedido Y atrasado", tornando a conversa muito mais humana e eficiente.

Passo 6: Segurança e Boas Práticas

A automação de mensagens, especialmente disparos em massa, requer cuidados rigorosos para evitar banimentos e vazamentos de dados.

Rate Limiting: Implemente delays entre as mensagens. Enviar 100 mensagens por segundo é uma bandeira vermelha para os algoritmos do WhatsApp. Utilize filas (como BullMQ ou RabbitMQ) para espalhar os envios ao longo do tempo.
Firewall e UFW: Não exponha as portas do seu gateway (ex: 8080) diretamente à internet. Use um proxy reverso como Nginx ou Traefik com autenticação básica ou tokens JWT para proteger os endpoints de webhook.
Backups: Faça backups regulares do diretório auth_info_baileys e do banco de dados PostgreSQL do Typebot. A perda dessas credenciais significa a necessidade de reescanear o QRCode, interrompendo a automação.
Logs: Monitore os logs do container para detectar erros de conexão ou limites de envio excedidos. Ferramentas como ELK Stack ou Loki/Grafana são ideais para isso.

Conclusão e Próximos Passos

A combinação de Typebot, IA Generativa e gateways self-hosted como o baseado em Baileys oferece um poder de automação sem precedentes para equipes de TI e desenvolvimento. Você não está preso a tabelas de preços por conversa, tem controle total sobre os dados dos seus clientes e pode criar fluxos lógicos complexos que se adaptam ao comportamento do usuário em tempo real.

Para avançar, considere implementar:

Upload de Arquivos: Configure o Typebot para receber imagens ou PDFs enviados pelo WhatsApp e processá-los via IA (OCR ou análise de documentos).
Pagamentos: Integre com gateways de pagamento (como Mercado Pago ou Stripe) dentro do fluxo do bot para fechar vendas automaticamente.
Otimização de Custos: Use modelos de IA open-source locais (via Ollama ou vLLM) em sua GPU para reduzir custos operacionais de chamadas à API.

Lembre-se: a tecnologia é o facilitador, mas a estratégia de comunicação é o que gera valor. Utilize esses recursos para criar experiências úteis, rápidas e respeitosas com seu usuário. Com essa base sólida em Docker e APIs, sua infraestrutura de comunicação está pronta para escalar junto com o seu negócio.

Tags: #typebot whatsapp #chatbot self hosted #typebot tutorial #automacao whatsapp #baileys nodejs #ia generativa chatbot #docker compose typebot #webhook typebot