Voltar para a landing
Tutorial de instalação
Do servidor zerado ao WhatsApp no Chatwoot
Guia completo passo a passo. Funciona mesmo sem ser técnico — você cria a VPS, cola um comando, responde algumas perguntas e está no ar.
Visão rápida — ordem dos passos
- Criar a VPS (Hetzner ou similar)
- Criar o Tunnel na Cloudflare e pegar o token
- Rodar o instalador na VPS com um comando
- Criar os 4 endereços públicos na Cloudflare
- Configurar o Chatwoot — conta + caixa de entrada API
- Configurar o painel Bridge — Base URL + tenant
- Parear o WhatsApp
- Verificar no Portainer — stacks e containers
1
Criar a VPS na Hetzner
- Acesse o Hetzner Cloud Console → New Project (ou use um existente).
- Clique em Add Server e configure:
- Location: a mais próxima dos seus clientes (ex.: Ashburn/EUA ou Alemanha).
- Image: Ubuntu 24.04.
- Type: mínimo recomendado CPX21 (2 vCPU / 4 GB RAM).
- Networking: IPv4 público habilitado.
- SSH Key: adicione sua chave (recomendado) ou use senha por e-mail.
- Clique em Create & Buy now. Anote o IP público do servidor.
Acessar por SSH
local:~$
ssh root@SEU_IP
2
Criar o Tunnel na Cloudflare
O Tunnel entrega HTTPS automático sem abrir portas no servidor e sem mexer em DNS manualmente.
- Abra o Cloudflare Zero Trust → Networks → Tunnels → Create a tunnel.
- Tipo: Cloudflared → dê um nome (ex.:
atendimento) → Save. - Na tela "Install connector", copie o token — o texto longo depois de
--token, começa comeyJ.... Guarde-o, você vai colar no instalador. - Não feche — os endereços públicos são criados no passo 4.
3
Rodar o instalador na VPS
Na VPS (como root), cole o comando abaixo e pressione Enter:
root@vps:~#
bash <(curl -fsSL https://raw.githubusercontent.com/giovani-junior-dev/megaAPI-Chatwoot/master/install-pack/bootstrap.sh)
O instalador vai perguntar — responda com calma e atenção aos domínios:
| Pergunta | Exemplo | Observação |
|---|---|---|
| Hostname do Chatwoot | chatwoot.suaempresa.com | 1 nível de subdomínio |
| Hostname do Bridge | bridge.suaempresa.com | painel de administração |
| Hostname do Portainer | portainer.suaempresa.com | gerenciador de containers |
| Hostname do Backup | backup.suaempresa.com | painel de backups |
| Token do Tunnel | eyJ... | copiado no passo 2 |
| E-mail do admin (Bridge) | voce@suaempresa.com | login do painel Bridge |
| Senha do admin (Bridge) | (sua senha) | login do painel Bridge |
| Senha do admin (Portainer) | (sua senha) | mínimo 12 caracteres |
Erros comuns a evitar: Digite o domínio sem typos (ex.: chatwoot, não chtwoot) — um erro aqui quebra os links de mídia. Use subdomínio de 1 nível (chatwoot.suaempresa.com). Dois níveis (chat.chatwoot.suaempresa.com) quebram o HTTPS gratuito da Cloudflare.
O resto — senhas de banco, chaves de criptografia — é gerado automaticamente. O instalador sobe tudo, prepara o banco do Chatwoot e cria os administradores. Leva alguns minutos (a primeira vez baixa as imagens Docker). Ao final, um resumo com os endereços é exibido.
4
Criar os 4 endereços públicos na Cloudflare
Volte ao Tunnel → aba Public Hostnames → Add a public hostname. Faça isso 4 vezes. Em todos, o Type é HTTP (o HTTPS é entregue pela Cloudflare):
| Subdomain | Domain | Type | URL (Service) |
|---|---|---|---|
chatwoot | suaempresa.com | HTTP | chatwoot_admin:3000 |
bridge | suaempresa.com | HTTP | bridge:8080 |
portainer | suaempresa.com | HTTP | portainer:9000 |
backup | suaempresa.com | HTTP | pgbackupweb:8085 |
Os subdomínios precisam bater exatamente com os hostnames informados no instalador. Após salvar, o Tunnel deve aparecer como HEALTHY.
5
Configurar o Chatwoot
- Acesse
https://chatwoot.suaempresa.com→ crie a conta de administrador. - Crie a caixa de entrada do tipo API:
- Menu → Caixas de entrada → Adicionar caixa de entrada → API.
- Dê um nome (ex.:
WhatsApp) → criar. - Anote o Inbox ID — aparece na URL da caixa de entrada.
- Pegue os dados que o Bridge vai pedir:
- Account ID: está na URL
/app/accounts/<ID>. - Token de acesso: Perfil → Configurações do perfil → Token de Acesso.
- Account ID: está na URL
Crie a caixa de entrada ANTES de criar o tenant no Bridge. Se inverter, o Bridge avisa com uma mensagem clara e não cria nada incompleto.
6
Configurar o painel Bridge
- Acesse
https://bridge.suaempresa.com→ entre com o e-mail e senha definidos no instalador. - Vá em Configurações → preencha a Base URL =
https://bridge.suaempresa.com→ salvar. - Vá em Novo tenant e preencha:
- Slug: identificador curto, minúsculo, com hífen (ex.:
empresa-x). Sem espaços. - megaAPI: host, instância e token da sua instância.
- Chatwoot: URL (
https://chatwoot.suaempresa.com), token de acesso, Account ID e Inbox ID.
- Slug: identificador curto, minúsculo, com hífen (ex.:
- Salvar. O Bridge configura o webhook do Chatwoot automaticamente (com token de segurança).
O que cada página do painel Bridge faz
| Página | Rota | O que faz |
|---|---|---|
| Login | /login | Autenticação do administrador (e-mail + senha). |
| Painel | / | Lista todos os tenants: slug, mensagens nas últimas 24h, status de pareamento e ações rápidas. |
| Novo tenant | /tenants/new | Assistente em 4 passos para cadastrar um tenant. Configura o webhook automaticamente. |
| Diagnóstico | /tenants/{slug}/diag | Verifica a saúde do tenant — conectividade e configuração. |
| Mensagens | /messages | Histórico de mensagens por tenant com filtro e paginação. |
| DLQ | /dlq | Fila de mensagens que falharam, com botão de reenviar por mensagem. |
| Configurações | /settings | Define a Base URL pública do Bridge. Obrigatório antes de criar tenants. |
| Pareamento | /pair/{slug} | Página para conectar o WhatsApp: QR Code, código de pareamento e status em tempo real. |
7
Parear o WhatsApp
- No Painel do Bridge, na linha do tenant, clique em Gerar link de pareamento.
- Abra o link → escaneie o QR Code com o WhatsApp do celular (ou use o código de pareamento).
- Quando o status mudar para conectado, faça o teste:
- Envie uma mensagem do WhatsApp → deve aparecer no Chatwoot.
- Responda no Chatwoot → deve chegar no WhatsApp, com texto e arquivo.
8
Verificar no Portainer
- Acesse
https://portainer.suaempresa.com→ entre com admin + a senha do instalador. - Selecione o ambiente swarm-local → menu Stacks.
- Confira que as stacks não estão como "Limited" — devem aparecer editáveis:
postgres,cloudflared,chatwoot,bridge,pgbackupweb. - Em Services / Containers, todos devem estar running (verde):
chatwoot_admin,chatwoot_api,chatwoot_sidekiq,chatwoot_redis,postgres,cloudflared,bridge,pgbackupweb,portainer,agent.
Se alguma stack aparecer como Limited ou faltar o ambiente swarm-local, aguarde 1–2 min e recarregue — o instalador registra o ambiente assim que o agente sobe.
?
Resolvendo problemas
| Sintoma | Causa provável / solução |
|---|---|
| Tunnel DOWN | Token errado no install. Refaça o passo do token e reinstale o connector. |
| Página não abre / erro de SSL | Subdomínio de 2 níveis. Use 1 nível (chatwoot.suaempresa.com). |
| Imagem/vídeo "não disponível" no Chatwoot | Hostname do Chatwoot digitado errado no install (ex.: chtwoot). Corrija o FRONTEND_URL para o domínio certo e reinicie o Chatwoot. |
| Envio do Chatwoot dá "Falha ao enviar" | A caixa de entrada foi criada depois do tenant. Recrie o tenant com a caixa de entrada já existente. |
| Stacks aparecem como Limited | O ambiente do Portainer não registrou no momento certo. Aguarde 1–2 min e recarregue. |
| Mensagem do WhatsApp não chega | Mensagens de grupos/canais não são atendimentos 1:1. Use conversas diretas para testar. |
✓
Acessos finais
| Ferramenta | URL | Login |
|---|---|---|
| Chatwoot | https://chatwoot.suaempresa.com | conta criada no passo 5 |
| Bridge (painel) | https://bridge.suaempresa.com | e-mail + senha do install |
| Portainer | https://portainer.suaempresa.com | admin + senha do install |
| Backup | https://backup.suaempresa.com | admin do pgbackweb |