A automação de atendimento via WhatsApp deixou de ser um diferencial competitivo para se tornar uma necessidade fundamental para empresas que buscam escala e eficiência operacional. No entanto, o uso de APIs oficiais do WhatsApp (Meta) pode ser custoso e limitado para cenários de alto volume ou testes locais. É aqui que soluções self-hosted baseadas em protocolos não-oficiais ganham destaque, permitindo o controle total da infraestrutura e a criação de chatbots IA personalizados.
Neste tutorial técnico, vamos demonstrar como criar uma integração robusta entre o Typebot, uma plataforma low-code para construção de fluxos conversacionais, e o WhatsApp através da biblioteca Baileys. Essa abordagem permite que você hospede seu próprio gateway de mensagens, conectando-o ao Typebot para orquestrar a lógica do bot, e utilize ferramentas como Chatwoot para gerenciamento omnichannel.
Entendendo a Arquitetura da Solução
Antes de partir para a implementação, é crucial compreender como os componentes se comunicam. A arquitetura proposta segue o padrão de gateway:
- Baileys: Uma biblioteca Node.js que implementa o protocolo WhatsApp Web. Ela gerencia a conexão WebSocket com os servidores da Meta, lidando com QR Codes, autenticação e roteamento de mensagens.
- Typebot: O motor de lógica. Recebe as mensagens do usuário (via webhook), processa-as através dos fluxos visuais criados na plataforma e retorna a resposta desejada.
- Node.js/Express: Uma camada intermediária (script customizado) que atua como ponte. Ela escuta os eventos do Baileys, formata o payload para o formato JSON esperado pelo Typebot e envia a resposta de volta para o WhatsApp.
Essa separação de responsabilidades garante modularidade. Você pode trocar o motor de IA ou o gateway de mensagens sem refazer toda a aplicação.
Pré-requisitos e Preparação do Ambiente
Para executar esta solução, você precisará de um servidor Linux (Ubuntu 20.04+ recomendado) com acesso root ou sudo, e Docker instalado para facilitar o gerenciamento do Typebot. A linguagem principal será JavaScript/Node.js.
Comece atualizando o sistema e instalando as dependências básicas:
sudo apt update
sudo apt upgrade -y
sudo apt install curl git build-essential libssl-dev -yVamos instalar o Node.js (versão LTS recomendada) utilizando o NodeSource:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejsVerifique as versões instaladas para garantir que tudo está correto:
node --version
npm --versionPasso 1: Implantando o Typebot com Docker
O Typebot requer um banco de dados PostgreSQL e um serviço de storage. A maneira mais limpa é utilizar Docker Compose.
Crie um diretório para o projeto:
mkdir typebot-whatsapp && cd typebot-whatsappCrie o arquivo docker-compose.yml com a seguinte configuração:
version: '3.8'
services:
typebot-server:
image: baptisteAr/typebot-server
environment:
- DATABASE_URL=postgresql://postgres:password@db:5432/typebot
- JWT_SECRET=seu_jwt_seguro_aqui
- NEXT_PUBLIC_BASE_URL=http://localhost:3000
ports:
- "3000:3000"
depends_on:
- db
db:
image: postgres:15-alpine
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=password
- POSTGRES_DB=typebot
volumes:
- db_data:/var/lib/postgresql/data
volumes:
db_data:Inicie os containers:
docker-compose up -dAcesse http://localhost:3000 para configurar o administrador do Typebot. Crie um novo bot e, dentro das configurações do fluxo, ative a opção "Webhook" ou "API Endpoint". Copie a URL gerada pelo Typebot (ex: https://seu-tipo-bot.typebot.io/api/v1/bot/ID_DO_BOT), pois ela será necessária no script de conexão.
Passo 2: Configurando o Gateway WhatsApp com Baileys
Agora, vamos criar a aplicação Node.js que fará a ponte. Crie uma nova pasta para o gateway:
mkdir whatsapp-gateway && cd whatsapp-gateway
npm init -y
npm install @whiskeysockets/baileys express axios qrcode-terminalA biblioteca Baileys (sucessora do Baileys original) é leve e eficiente. A instalação do qrcode-terminal facilitará o login inicial diretamente no console.
Passo 3: Escrevendo o Script de Integração
Crie o arquivo index.js. Este script fará três coisas principais:
- Autenticar e conectar ao WhatsApp via Baileys.
- Escutar novas mensagens recebidas.
- Encaminhar essas mensagens para o Typebot e enviar a resposta de volta.
Abra o arquivo em seu editor de texto e insira o seguinte código base:
const { default: makeWASocket, useMultiFileAuthState, DisconnectReason } = require('@whiskeysockets/baileys');
const qrcode = require('qrcode-terminal');
const axios = require('axios');
const express = require('express');
// Configurações
const TYPEBOT_WEBHOOK_URL = 'SUA_URL_DO_TYPEBOT_AQUI';
const PORT = 4000;
async function connectToWhatsApp() {
const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys');
const sock = makeWASocket({
auth: state,
printQRInTerminal: true,
mobile: false // Defina como true se estiver simulando um dispositivo móvel
});
sock.ev.on('creds.update', saveCreds);
// Evento: Nova mensagem recebida
sock.ev.on('messages.upsert', async (msg) => {
const message = msg.messages[0];
if (!message || !message.message) return;
const textMsg = message.message.conversation || message.message.extendedTextMessage?.text;
if (!textMsg) return;
const senderNumber = message.key.remoteJid.split('@')[0];
console.log(`Mensagem de ${senderNumber}: ${textMsg}`);
// Chamar o Typebot
try {
const response = await axios.post(TYPEBOT_WEBHOOK_URL, {
inputs: [
{
name: 'nomeDoInputNoTypebot', // Nome da variável de entrada no Typebot
value: textMsg
}
],
threadId: message.key.remoteJid
});
// Processar resposta do Typebot e enviar ao usuário
// A estrutura de retorno depende de como o Typebot retorna os dados
// Geralmente é um array de ações ou texto
const botResponse = response.data?.outputs?.[0]?.value || 'Erro ao processar';
await sock.sendMessage(message.key.remoteJid, { text: botResponse });
} catch (error) {
console.error('Erro ao chamar Typebot:', error);
await sock.sendMessage(message.key.remoteJid, { text: 'Desculpe, ocorreu um erro no servidor.' });
}
});
// Evento: Conexão fechada
sock.ev.on('connection.update', async (update) => {
const { connection, lastDisconnect } = update;
if (connection === 'close') {
const shouldReconnect = lastDisconnect.error?.output?.statusCode !== DisconnectReason.loggedOut;
console.log('Conexão perdida, reconectando...', shouldReconnect);
setTimeout(connectToWhatsApp, 5000);
} else if (connection === 'open') {
console.log('Conexão estabelecida com sucesso!');
}
});
}
// Iniciar a aplicação Express para Webhooks (opcional para disparos em massa ou gestão)
const app = express();
app.use(express.json());
app.post('/webhook/whatsapp', (req, res) => {
// Lógica para receber notificações de status ou disparos externos
res.sendStatus(200);
});
app.listen(PORT, () => {
console.log(`Servidor rodando na porta ${PORT}`);
connectToWhatsApp();
});Atenção: Você deve substituir SUA_URL_DO_TYPEBOT_AQUI pela URL do seu endpoint e ajustar o nome da variável de entrada (nomeDoInputNoTypebot) conforme configurado no seu fluxo do Typebot.
Passo 4: Executando e Autenticando
Com o código pronto, inicie a aplicação:
node index.jsO terminal exibirá um QR Code. Abra o aplicativo do WhatsApp no seu celular, vá em Dispositivos Conectados > Conectar um Dispositivo e escaneie o código.
Após o scan, a conexão será estabelecida e o log "Conexão estabelecida com sucesso!" aparecerá. O bot está agora online e pronto para receber mensagens.
Passo 5: Avançando para Chatwoot e Disparos em Massa
Para ambientes de produção, enviar respostas manualmente via script Node.js pode ser insuficiente. Aqui entram conceitos avançados de integração.
Integração com Chatwoot
O Chatwoot atua como uma central de atendimento unificada. Para integrar:
- No Chatwoot, crie um canal "WhatsApp" e selecione a opção "Self Hosted".
- Configure o número do WhatsApp que você está usando no Baileys.
- O script Baileys deve ser modificado para enviar as mensagens de saída não diretamente ao usuário, mas sim para a API do Chatwoot, ou vice-versa, sincronizando os IDs da conversa.
Isto requer mapear o remoteJid (ex: [email protected]) para o contato no Chatwoot. Utilize a API do Chatwoot para criar/atualizar contatos e enviar mensagens.
Disparos em Massa e Webhooks
O protocolo não-oficial do WhatsApp possui restrições rigorosas contra spam. Para realizar disparos em massa, é altamente recomendável:
- Usar pausas aleatórias entre as mensagens para evitar detecção de bot.
- Monitorar a reputação do número.
- Implementar filas (como BullMQ ou RabbitMQ) para gerenciar o throughput.
Além disso, configure webhooks no seu script Express. Quando o Typebot processa um fluxo complexo, ele pode precisar de dados externos. Seu servidor pode expor endpoints que o Baileys consulta ou que o Typebot chama para obter informações em tempo real (como saldo bancário ou status de pedido).
Considerações Finais e Boas Práticas
A implementação de chatbots IA via Baileys oferece flexibilidade total, mas carrega riscos. A Meta atualiza constantemente seus protocolos, o que pode quebrar conexões inesperadamente. Mantenha a biblioteca Baileys sempre atualizada (npm update).
Outro ponto crítico é a segurança. Nunca exponha suas credenciais de sessão (pastas geradas pelo Baileys) publicamente. Utilize variáveis de ambiente para armazenar URLs de webhooks e segredos.
Para escalabilidade, considere containerizar o gateway Node.js junto com o Typebot em um cluster Docker Swarm ou Kubernetes, utilizando balanceamento de carga se você precisar gerenciar múltiplos números de WhatsApp simultaneamente.
Com esta estrutura, você possui uma base sólida para criar assistentes virtuais sofisticados, integrando IA generativa (como OpenAI ou LLaMA) nos fluxos do Typebot, oferecendo respostas naturais e contextuais aos seus usuários no WhatsApp.