Este guia sobe o Typebot e a Evolution API na mesma VPS Ubuntu 24.04 com Docker Compose e Caddy na frente. Só o Caddy publica portas na internet, com HTTPS automático. A Evolution API conversa com o Viewer do Typebot pela rede interna do Compose, sem tráfego externo entre os dois serviços.
Neste artigo
As configurações abaixo seguem o repositório oficial do Typebot v3.19.1 e o código-fonte da Evolution API v2.3.7, com imagens travadas em postgres:16.16, postgres:15.20, redis:7.4.12 e caddy:2.11.9. Se você prefere subir só a Evolution API ou juntá-la com o n8n, veja Como instalar a Evolution API em uma VPS e n8n e Evolution API na mesma VPS.
O que você vai precisar
- Uma VPS com Ubuntu 24.04 de 64 bits, Docker Engine com Compose plugin e acesso SSH com
sudo. - Três subdomínios apontando em registro
Apara o IPv4 da VPS:builder.example.com(editor do Typebot),bot.example.com(viewer do Typebot) eapi.example.com(Evolution API). - Um e-mail para a conta ACME do Caddy e um servidor SMTP (ou credenciais OAuth do Google/GitHub) para o login do Typebot.
São oito contêineres: Caddy, Typebot Builder, Typebot Viewer, PostgreSQL 16 do Typebot, Redis do Typebot, Evolution API, PostgreSQL 15 da API e Redis da API. Trate 4 vCPU e 8 GB de RAM como piso apertado para rodar tudo junto sem disputa de memória. O cartão ao lado aponta um plano acima disso para sobrar margem para várias instâncias e sessões simultâneas.
Se o Docker ainda não estiver instalado na VPS, siga o repositório apt oficial descrito em Como instalar o n8n com Docker numa VPS.
Como os três endereços se conversam
O Typebot separa o editor (typebot-builder) de quem executa os fluxos (typebot-viewer). Os dois escutam a porta 3000 dentro dos contêineres, mas precisam de domínios públicos diferentes no navegador: a documentação de configuração do Typebot exige hostnames distintos entre NEXTAUTH_URL e NEXT_PUBLIC_VIEWER_URL porque cookies de navegador ignoram a porta.
Na integração com o WhatsApp, a Evolution API (8080) nunca chama o Builder. Ela envia o início e a continuação de cada conversa para o Viewer, nos endpoints /api/v1/typebots/<publicId>/startChat e /api/v1/sessions/<sessionId>/continueChat. Como os dois serviços estão no mesmo Docker Compose, a Evolution API pode chamar http://typebot-viewer:3000 diretamente pela rede interna.

Preparar os arquivos
Crie a pasta do projeto. O nome dela vira o prefixo dos volumes no Docker:
mkdir -p ~/typebot-whatsapp && cd ~/typebot-whatsappSegredos e variáveis de ambiente
O Typebot exige ENCRYPTION_SECRET com 32 caracteres no formato base64. Gere essa chave com o comando da documentação oficial e gere as demais senhas em hexadecimal:
openssl rand -base64 24 | tr -d '\n' ; echo
openssl rand -hex 16Rode o primeiro comando uma vez para ENCRYPTION_SECRET e o segundo três vezes: senha do PostgreSQL do Typebot, senha do PostgreSQL da Evolution API e AUTHENTICATION_API_KEY. Não reutilize os valores de exemplo dos repositórios.
Crie o .env com os domínios, os bancos, o SMTP do Typebot e a integração nativa habilitada na Evolution API:
BUILDER_DOMAIN=builder.example.com
VIEWER_DOMAIN=bot.example.com
EVOLUTION_DOMAIN=api.example.com
[email protected]
TYPEBOT_VERSION=3.19.1
TYPEBOT_ENCRYPTION_SECRET=cole-aqui-os-32-caracteres-base64
[email protected]
TYPEBOT_POSTGRES_USER=typebot
TYPEBOT_POSTGRES_PASSWORD=cole-a-senha-do-typebot
TYPEBOT_POSTGRES_DB=typebot
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=usuario-smtp
SMTP_PASSWORD=senha-smtp
NEXT_PUBLIC_SMTP_FROM='Typebot <[email protected]>'
SMTP_SECURE=false
EVOLUTION_API_KEY=cole-a-chave-da-evolution
EVOLUTION_POSTGRES_USER=evolution
EVOLUTION_POSTGRES_PASSWORD=cole-a-senha-da-evolution
EVOLUTION_POSTGRES_DB=evolution_dbRestrinja a leitura do arquivo:
chmod 600 .envPontos que evitam erro logo na primeira subida:
TYPEBOT_ENCRYPTION_SECRETprecisa ser idêntica no Builder e no Viewer. Se você trocar depois, sessões existentes e credenciais salvas nos fluxos deixam de ser lidas.TYPEBOT_ADMIN_EMAILlibera o planoUNLIMITEDno workspace assim que você cria a conta com esse e-mail, evitando o limite de 200 chats do planoFREE.- Se a senha de qualquer banco contiver
@,:,/ou#, use apenas caracteres hexadecimais (openssl rand -hex 16) ou codifique em percentual na URI. - Caso prefira entrar no Typebot com Google ou GitHub em vez de e-mail mágico via SMTP, substitua o bloco SMTP por
GOOGLE_AUTH_CLIENT_IDeGOOGLE_AUTH_CLIENT_SECRET(callback emhttps://builder.example.com/api/auth/callback/google), conforme a documentação de configuração do Typebot.
Caddyfile
Crie o Caddyfile na mesma pasta. O flush_interval -1 no bloco do Viewer segue a documentação oficial do Typebot para habilitar streaming de mensagens sem buffer no proxy:
{
email {$ACME_EMAIL}
}
{$BUILDER_DOMAIN} {
reverse_proxy typebot-builder:3000
}
{$VIEWER_DOMAIN} {
reverse_proxy typebot-viewer:3000 {
flush_interval -1
}
}
{$EVOLUTION_DOMAIN} {
reverse_proxy evolution-api:8080
}Docker Compose
O arquivo abaixo parte do docker-compose.yml oficial do Typebot v3.19.1 (já com Redis obrigatório no serviço) e do Compose da Evolution API v2.3.7, sem a rede externa do Dokploy e com cada serviço recebendo apenas as variáveis de que precisa:
x-typebot-common: &typebot-common
restart: always
depends_on:
typebot-db:
condition: service_healthy
typebot-redis:
condition: service_healthy
environment:
DATABASE_URL: postgresql://${TYPEBOT_POSTGRES_USER}:${TYPEBOT_POSTGRES_PASSWORD}@typebot-db:5432/${TYPEBOT_POSTGRES_DB}
REDIS_URL: redis://typebot-redis:6379
ENCRYPTION_SECRET: ${TYPEBOT_ENCRYPTION_SECRET}
NODE_OPTIONS: --no-node-snapshot
NEXTAUTH_URL: https://${BUILDER_DOMAIN}
NEXT_PUBLIC_VIEWER_URL: https://${VIEWER_DOMAIN}
ADMIN_EMAIL: ${TYPEBOT_ADMIN_EMAIL}
SMTP_HOST: ${SMTP_HOST}
SMTP_PORT: ${SMTP_PORT}
SMTP_USERNAME: ${SMTP_USERNAME}
SMTP_PASSWORD: ${SMTP_PASSWORD}
NEXT_PUBLIC_SMTP_FROM: ${NEXT_PUBLIC_SMTP_FROM}
SMTP_SECURE: ${SMTP_SECURE}
services:
caddy:
image: caddy:2.11.9
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
environment:
BUILDER_DOMAIN: ${BUILDER_DOMAIN}
VIEWER_DOMAIN: ${VIEWER_DOMAIN}
EVOLUTION_DOMAIN: ${EVOLUTION_DOMAIN}
ACME_EMAIL: ${ACME_EMAIL}
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
depends_on:
- typebot-builder
- typebot-viewer
- evolution-api
typebot-db:
image: postgres:16.16
restart: always
environment:
POSTGRES_USER: ${TYPEBOT_POSTGRES_USER}
POSTGRES_PASSWORD: ${TYPEBOT_POSTGRES_PASSWORD}
POSTGRES_DB: ${TYPEBOT_POSTGRES_DB}
volumes:
- typebot_db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${TYPEBOT_POSTGRES_USER} -d ${TYPEBOT_POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
typebot-redis:
image: redis:7.4.12
restart: always
command: redis-server --save 60 1 --loglevel warning
volumes:
- typebot_redis:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
start_period: 20s
interval: 15s
timeout: 3s
retries: 5
typebot-builder:
<<: *typebot-common
image: baptistearno/typebot-builder:${TYPEBOT_VERSION}
typebot-viewer:
<<: *typebot-common
image: baptistearno/typebot-viewer:${TYPEBOT_VERSION}
evolution-postgres:
image: postgres:15.20
restart: always
environment:
POSTGRES_USER: ${EVOLUTION_POSTGRES_USER}
POSTGRES_PASSWORD: ${EVOLUTION_POSTGRES_PASSWORD}
POSTGRES_DB: ${EVOLUTION_POSTGRES_DB}
command: ["postgres", "-c", "max_connections=1000"]
volumes:
- evolution_postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${EVOLUTION_POSTGRES_USER} -d ${EVOLUTION_POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
evolution-redis:
image: redis:7.4.12
restart: always
command: redis-server --port 6379 --appendonly yes
volumes:
- evolution_redis:/data
evolution-api:
image: evoapicloud/evolution-api:v2.3.7
restart: always
depends_on:
evolution-postgres:
condition: service_healthy
evolution-redis:
condition: service_started
environment:
SERVER_URL: https://${EVOLUTION_DOMAIN}
AUTHENTICATION_API_KEY: ${EVOLUTION_API_KEY}
DATABASE_PROVIDER: postgresql
DATABASE_CONNECTION_URI: postgresql://${EVOLUTION_POSTGRES_USER}:${EVOLUTION_POSTGRES_PASSWORD}@evolution-postgres:5432/${EVOLUTION_POSTGRES_DB}?schema=evolution_api
DATABASE_CONNECTION_CLIENT_NAME: evolution
CACHE_REDIS_ENABLED: "true"
CACHE_REDIS_URI: redis://evolution-redis:6379/6
CACHE_REDIS_PREFIX_KEY: evolution
TYPEBOT_ENABLED: "true"
TYPEBOT_API_VERSION: latest
TELEMETRY_ENABLED: "false"
LOG_LEVEL: ERROR,WARN,INFO,LOG,WEBHOOKS
LANGUAGE: en
volumes:
- evolution_instances:/evolution/instances
volumes:
caddy_data:
caddy_config:
typebot_db:
typebot_redis:
evolution_postgres:
evolution_redis:
evolution_instances:Duas linhas da evolution-api são decisivas e costumam ser esquecidas:
TYPEBOT_ENABLED: "true": no.env.exampleda Evolution API o valor padrão éfalse. Sem ligar essa chave, toda chamada em/typebot/*devolve400 Bad RequestcomTypebot is disabled.TYPEBOT_API_VERSION: latest: faz a Evolution API usar as rotas atuais do Typebot (/api/v1/typebots/<slug>/startChate/api/v1/sessions/<id>/continueChat) em vez da rota legada/api/v1/sendMessage.
Se você quiser enviar imagens ou arquivos dentro dos blocos do Typebot, adicione um bucket compatível com S3 (como MinIO ou Cloudflare R2) seguindo a documentação de S3 do Typebot. Fluxos de texto, menus e coleta de variáveis funcionam sem S3.
Subir e validar os três domínios
Antes de subir, confira se builder.example.com, bot.example.com e api.example.com já resolvem para o IPv4 da VPS e se as portas 80 e 443 estão liberadas no firewall. Depois suba a stack:
cd ~/typebot-whatsapp
sudo docker compose up -d
sudo docker compose psNa primeira subida, o typebot-builder e a evolution-api aplicam as migrações do Prisma nos respectivos bancos. Acompanhe os logs até ambos ficarem prontos:
sudo docker compose logs -f typebot-builder typebot-viewer evolution-apiConfira os três endereços com HTTPS válido:
curl -fsS -I https://builder.example.com
curl -fsS -I https://bot.example.com
curl -fsS https://api.example.comO api.example.com devolve JSON com a versão 2.3.7 e a mensagem de boas-vindas da Evolution API. Se algum certificado não sair, veja os logs do Caddy com sudo docker compose logs caddy e confirme o DNS.
Criar e publicar o fluxo no Typebot
- Abra
https://builder.example.come faça login com o e-mail definido emTYPEBOT_ADMIN_EMAIL. - Crie um fluxo novo (por exemplo, um menu de atendimento com um bloco de boas-vindas e uma pergunta de escolha).
- Clique em Publish no topo direito. Um fluxo em rascunho não responde na API do Viewer.
- Na aba Share, copie o identificador público do bot (o slug que aparece depois de
https://bot.example.com/, por exemploatendimento-whatsapp).
Assim que a conta admin estiver criada, vale adicionar DISABLE_SIGNUP: "true" no bloco x-typebot-common do docker-compose.yml e recriar o Builder (sudo docker compose up -d typebot-builder) para impedir cadastros abertos na sua instância.
Teste se o Viewer responde à API pública antes de ligar a Evolution API:
curl -fsS -X POST https://bot.example.com/api/v1/typebots/atendimento-whatsapp/startChat \
-H "Content-Type: application/json" \
-d '{}'Se a resposta trouxer sessionId e o array messages com a primeira fala do fluxo, o Typebot está pronto.
Conectar a Evolution API ao Typebot
Carregue as variáveis do .env na sessão do terminal para não digitar a chave da API na mão:
cd ~/typebot-whatsapp
set -a && . ./.env && set +a1. Criar a instância e parear o WhatsApp
Crie a instância usando WHATSAPP-BAILEYS (a documentação da Evolution API lembra que a conexão via WhatsApp Web pode ter limitações em relação à API oficial da Meta):
curl -fsS -X POST "https://${EVOLUTION_DOMAIN}/instance/create" \
-H "apikey: $EVOLUTION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"instanceName":"atendimento","integration":"WHATSAPP-BAILEYS","qrcode":false}'Peça o QR Code e escaneie no WhatsApp do celular em Aparelhos conectados:
curl -fsS "https://${EVOLUTION_DOMAIN}/instance/connect/atendimento" \
-H "apikey: $EVOLUTION_API_KEY"2. Definir os padrões de sessão
O endpoint /typebot/settings/<instancia> grava o comportamento padrão de expiração, pausa e encerramento das conversas:
curl -fsS -X POST "https://${EVOLUTION_DOMAIN}/typebot/settings/atendimento" \
-H "apikey: $EVOLUTION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expire": 20,
"keywordFinish": "#sair",
"delayMessage": 1000,
"unknownMessage": "Não entendi. Digite #sair para encerrar.",
"listeningFromMe": false,
"stopBotFromMe": true,
"keepOpen": false,
"debounceTime": 3,
"ignoreJids": ["@g.us"]
}'O que cada campo faz no código da Evolution API v2.3.7:
expire: minutos de inatividade até a sessão expirar.keywordFinish: palavra que encerra a sessão atual (#sair).stopBotFromMe: true: pausa o bot se um atendente responder pelo mesmo aparelho.listeningFromMe: false: evita que mensagens enviadas pelo próprio número disparem o bot.ignoreJids: ["@g.us"]: ignora grupos do WhatsApp e responde apenas conversas privadas.
3. Vincular o fluxo publicado
Agora registre o bot na instância apontando url para o Viewer na rede interna (http://typebot-viewer:3000, sem barra no final) e typebot para o slug público do fluxo:
curl -fsS -X POST "https://${EVOLUTION_DOMAIN}/typebot/create/atendimento" \
-H "apikey: $EVOLUTION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"description": "Atendimento principal",
"url": "http://typebot-viewer:3000",
"typebot": "atendimento-whatsapp",
"triggerType": "keyword",
"triggerOperator": "contains",
"triggerValue": "oi",
"expire": 20,
"keywordFinish": "#sair",
"delayMessage": 1000,
"unknownMessage": "Não entendi. Digite #sair para encerrar.",
"listeningFromMe": false,
"stopBotFromMe": true,
"ignoreJids": ["@g.us"]
}'Para disparar em qualquer mensagem nova sem depender de palavra-chave, troque triggerType para "all" e remova triggerOperator e triggerValue.
Confirme se a regra ficou gravada:
curl -fsS "https://${EVOLUTION_DOMAIN}/typebot/find/atendimento" \
-H "apikey: $EVOLUTION_API_KEY"Variáveis preenchidas automaticamente
Ao abrir uma sessão em startChat, a Evolution API envia automaticamente em prefilledVariables:
remoteJid: identificador do contato no WhatsApp (por exemplo[email protected]).pushName: nome de exibição do contato.instanceName: nome da instância (atendimento).serverUrl,apiKeyeownerJid: dados da própria instância.
Crie variáveis com esses nomes exatos no Typebot se quiser saudar o cliente pelo nome ({{pushName}}) ou enviar o telefone ({{remoteJid}}) para um webhook ou CRM.
Backup e atualização
Os dados persistentes ficam em dois bancos PostgreSQL, no volume evolution_instances (sessões do WhatsApp) e no .env. Gere dumps dos dois bancos e o arquivo comprimido das sessões:
cd ~/typebot-whatsapp
set -a && . ./.env && set +a
sudo docker compose exec -T typebot-db pg_dump -U "$TYPEBOT_POSTGRES_USER" "$TYPEBOT_POSTGRES_DB" > typebot-$(date +%F).sql
sudo docker compose exec -T evolution-postgres pg_dump -U "$EVOLUTION_POSTGRES_USER" "$EVOLUTION_POSTGRES_DB" > evolution-$(date +%F).sql
sudo docker run --rm --volumes-from "$(sudo docker compose ps -q evolution-api)" -v "$PWD":/backup ubuntu:24.04 tar czf /backup/evolution-instances-$(date +%F).tar.gz /evolution/instancesCopie os .sql, o .tar.gz e o .env para fora da VPS. Um backup que fica só no mesmo disco se perde junto com o servidor.
Para atualizar o Typebot ou a Evolution API, faça o backup antes, leia as notas de versão no GitHub, troque o número da tag no .env ou no docker-compose.yml e recrie os contêineres:
cd ~/typebot-whatsapp
sudo docker compose pull
sudo docker compose up -dTrocar versão principal do PostgreSQL (16 ou 15) exige dump e restauração, não apenas troca de tag.
Próximo passo
- Se o WhatsApp pareou mas o bot ficou mudo, veja o checklist de diagnóstico em Typebot na Evolution API não responde no WhatsApp.
- Para escolher o servidor dessa stack, veja VPS para Evolution API ou VPS com Docker.