Chatwoot + Baileys: Centralize Atendimentos no WhatsApp

Introdução à Automação WhatsApp Self-Hosted

No cenário atual de atendimento ao cliente e marketing digital, o WhatsApp é o canal predominante no Brasil. No entanto, as soluções prontas (SaaS) frequentemente apresentam limitações de custo, personalização e controle de dados. Para empresas que buscam autonomia total, a abordagem self-hosted (hospedagem própria) surge como a solução definitiva.

Neste tutorial técnico, vamos demonstrar como integrar o Chatwoot, uma plataforma open-source de caixa de entrada unificada, com o motor de conexão Baileys. Essa combinação permite criar um sistema robusto de automação de WhatsApp, capaz de gerenciar tickets, atender chatbots IA e processar integrações via webhooks, tudo rodando em sua própria infraestrutura.

Diferente das APIs oficiais do Meta (Business API), que exigem aprovação de templates e cobrança por conversa, esta arquitetura utiliza o protocolo de comunicação padrão do WhatsApp Web. Isso significa zero custo por mensagem, total liberdade para criar fluxos lógicos complexos e controle absoluto sobre a latência e disponibilidade do seu bot.

Arquitetura da Solução

A arquitetura proposta baseia-se em três pilares fundamentais:

• Chatwoot: Interface de usuário (UI) para agentes humanos, dashboard de métricas e gestão de conversas.
• Baileys: Biblioteca Node.js que implementa o protocolo WebSocket do WhatsApp Web, servindo como o "motor" que envia e recebe mensagens.
• Webhooks/Integrações: Conexão entre o Chatwoot e serviços externos (como Typebot ou IA generativa) para processar a lógica de negócio.

A comunicação ocorre da seguinte forma: O Baileys escuta as mensagens entrantes do WhatsApp, envia um payload JSON para o webhook do Chatwoot. O Chatwoot cria/atualiza o ticket e dispara eventos (via Webhook Outgoing) para seus serviços de automação. A resposta final é enviada de volta ao Baileys, que a entrega no número do cliente.

Pré-requisitos de Infraestrutura

Antes de iniciar a instalação, certifique-se de ter acesso a um servidor Linux (recomendamos Ubuntu 20.04 ou 22.04 LTS) com os seguintes requisitos mínimos:

• CPU: Mínimo 2 vCPUs
• RAM: Mínimo 4GB (8GB recomendado para alta concorrência)
• Armazenamento: 40GB SSD
• Rede: Porta 443 e 5601 abertas, IP público estático.

Você precisará de privilégios de root ou usuário com permissões sudo. Também é essencial ter o Docker e o Docker Compose instalados no servidor.

Etapa 1: Preparação do Ambiente Docker

A maneira mais estável e reproduzível de implantar esta stack é utilizando containers. Vamos criar uma estrutura de diretórios para organizar os volumes de dados e configurações.

mkdir -p ~/chatwoot-baileys/{chatwoot,baileys,integrations}
cd ~/chatwoot-baileys

Crie o arquivo principal docker-compose.yml na raiz do projeto. Este arquivo definirá os serviços necessários: o banco de dados PostgreSQL, o Redis para fila de processos e o próprio Chatwoot.

version: '3'
services:
  postgres:
    image: postgres:15-alpine
    restart: always
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: chatwoot
      POSTGRES_USER: chatwoot
      POSTGRES_PASSWORD: senha_forte_aqui
    networks:
      - internal

  redis:
    image: redis:7-alpine
    restart: always
    command: redis-server --requirepass senha_redis_aqui
    volumes:
      - redis_data:/data
    networks:
      - internal

  chatwoot:
    image: chatwoot/chatwoot:latest
    restart: always
    ports:
      - "3000:3000"
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DATABASE: chatwoot
      POSTGRES_USERNAME: chatwoot
      POSTGRES_PASSWORD: senha_forte_aqui
      REDIS_URL: redis://:senha_redis_aqui@redis:6379
      RAILS_ENV: production
      SECRET_KEY_BASE: chave_secreta_gerada_pelo_rails
      ACCOUNT_LIMITATION_STRATEGY: block
    depends_on:
      - postgres
      - redis
    networks:
      - internal
      - external

volumes:
  db_data:
  redis_data:

networks:
  internal:
    driver: bridge
  external:
    driver: bridge

Importante: Substitua as senhas e a SECRET_KEY_BASE por valores aleatórios e seguros. A SECRET_KEY_BASE pode ser gerada executando o comando bundle exec rake secret em um ambiente Ruby ou usando geradores online de UUID v4.

Etapa 2: Inicialização do Chatwoot

Com o arquivo docker-compose.yml configurado, inicie os serviços:

docker compose up -d

Aguarde alguns minutos até que o container do Chatwoot esteja saudável. Você pode verificar o status com:

docker compose ps

Acesse http://SEU_IP:3000 no navegador. O Chatwoot solicitará a criação da primeira conta de administrador. Preencha os dados e conclua o setup inicial.

Etapa 3: Configuração do Canal WhatsApp Web (Baileys)

O Chatwoot possui suporte nativo para "WhatsApp Web" via conexão WebSocket, mas requer uma implementação específica para manter a sessão ativa e sincronizada. Utilizaremos uma adaptação do motor Baileys exposta como um serviço de webhook.

Crie o diretório baileys e adicione os arquivos necessários. Para fins didáticos, utilizaremos uma imagem pública ou um script Node.js simples que atua como ponte entre o WhatsApp Web e o Webhook do Chatwoot.

No entanto, a forma mais comum de integrar sem escrever código do zero é utilizando o recurso WhatsApp Cloud API se você tiver aprovação no Meta, ou usar soluções intermediárias open-source como o whatsapp-web.js (fork) configurado para enviar eventos ao Chatwoot.

Neste tutorial, focaremos na configuração dentro do painel do Chatwoot para habilitar a entrada de dados via webhook, que é onde seu motor Baileys conectará.

1. No painel do Chatwoot, vá em Ajustes (Settings) > Canais (Channels).
2. Clique em + Adicionar Canal.
3. Selecione WhatsApp Web.
4. Você verá uma URL de Webhook e um Token de Acesso. Copie estes valores.

Agora, seu serviço Baileys deve ser configurado para:

1. Escanear o QR Code (geralmente fornecido via API local do serviço).
2. Enviar eventos de message.create para a URL do Webhook copiada no passo anterior.

Exemplo de payload que seu script Baileys deve enviar ao Chatwoot:

curl -X POST "https://SEU_CHATWOOT_URL/api/v1/accounts/1/inbox_bot_webhooks" \
-H "Content-Type: application/json" \
-H "X-Custom-Webhook-Token: SEU_TOKEN_AQUI" \
-d '{
  "event": "message.created",
  "source_id": "5511999999999",
  "content": "Olá, como posso ajudar?"
}'

Nota: A estrutura exata do payload depende da versão do Chatwoot e do tipo de integração (Bot vs Agente). Consulte a documentação oficial de Webhooks do Chatwoot para mapear os campos corretos.

Etapa 4: Integração com Automação e IA

A verdadeira potência desta configuração surge quando conectamos o Chatwoot a ferramentas de automação. Vamos usar o Typebot ou um bot de IA como exemplo.

Configurando Webhooks de Saída (Outgoing)

No Chatwoot, vá em Ajustes > Canais > Selecione seu canal WhatsApp. Role até a seção Webhook.

Cole a URL do seu serviço de automação (ex: Typebot, Botpress, ou sua API customizada de IA).

https://SEU_TIPOBOT_URL/api/v1/run/ID_DO_FLUXO

Defina o evento que dispara o webhook. Recomendamos usar message.created.

Lógica de Resposta

Quando uma mensagem chega:

1. O Baileys envia para o Chatwoot.
2. O Chatwoot armazena a mensagem e dispara o Webhook de Saída.
3. Sua IA/Typebot processa a resposta.
4. Sua IA deve retornar uma resposta ao Chatwoot via API REST ou usar o recurso de Auto-resposta se estiver usando um fluxo visual que suporte callback.

Para respostas complexas, é comum utilizar a API do Chatwoot para criar a mensagem em nome do bot:

curl -X POST "https://SEU_CHATWOOT_URL/api/v1/accounts/1/conversations/CONVERSATION_ID/messages" \
-H "Content-Type: application/json" \
-d '{
  "message_type": "outgoing",
  "content": "Resposta processada pela IA.",
  "private": false
}'

Etapa 5: Segurança e Otimização

Para garantir a estabilidade e segurança da sua automação WhatsApp self-hosted, aplique as seguintes práticas:

1. Uso de Reverse Proxy (Nginx/Traefik)

Nunca exponha o Chatwoot diretamente pela porta 3000 em produção. Utilize um Nginx ou Traefik para gerenciar SSL/TLS e roteamento.

server {
    listen 443 ssl;
    server_name chat.seudominio.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. Rate Limiting no Baileys

O protocolo WhatsApp Web é sensível a picos de requisições. Se seu script Baileys enviar muitas mensagens em pouco tempo, o número pode ser banido temporariamente ou permanentemente.

Implemente filas (queues) usando Redis para desacoplar o envio das respostas. No Chatwoot, ative as Rate Limits nas configurações do canal para limitar quantas mensagens o sistema pode disparar por minuto.

3. Monitoramento de Sessão

O Baileys depende da sessão do navegador. Se a sessão cair (ex: logout em outro dispositivo), o serviço precisa reconectar. Implemente um healthcheck que monitora se o QR Code está válido. Se invalido, dispare um alerta via Slack ou Email para que um administrador possa escanear novamente.

Etapa 6: Manutenção e Backups

A persistência de dados é crucial. Certifique-se de que os volumes do Docker estão sendo monitorados.

# Exemplo de backup do banco de dados PostgreSQL
docker exec -t chatwoot-baileys-postgres-1 pg_dump -U chatwoot chatwoot > backup_$(date +%F).sql

Mantenha as imagens do Docker atualizadas regularmente para garantir compatibilidade com mudanças na API do WhatsApp Web:

docker compose pull
docker compose up -d

Considerações Finais sobre Compliance

Ao utilizar o Baileys e a automação WhatsApp, esteja ciente de que você está operando fora da API Oficial do Meta. Embora funcional, essa abordagem carrega riscos de bloqueio de número se houver denúncias dos usuários ou comportamento automatizado agressivo.

Recomendações de Boas Práticas:

• Nunca envie spam ou mensagens em massa não solicitadas.
• Ofereça sempre uma opção clara para falar com um humano (agente).
• Mantenha logs das conversas para auditoria e resolução de disputas.
• Utilize números "queimáveis" ou testadores para rodar testes intensivos.

A combinação Chatwoot + Baileys oferece uma flexibilidade inigualável para equipes que precisam de controle técnico profundo. Ao centralizar os atendimentos, você não apenas reduz custos operacionais, mas também cria um histórico unificado de interações que alimenta inteligência artificial e melhora a experiência do cliente final.

Com esta configuração em produção, sua infraestrutura está pronta para escalar atendimentos, integrar chatbots avançados e gerenciar múltiplos números de WhatsApp sob uma única interface administrativa profissional.