Ir para o conteúdo

Tutorial

Typebot e Evolution API na mesma VPS para WhatsApp

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
  1. O que você vai precisar
  2. Como os três endereços se conversam
  3. Preparar os arquivos
  4. Subir e validar os três domínios
  5. Criar e publicar o fluxo no Typebot
  6. Conectar a Evolution API ao Typebot
  7. Backup e atualização
  8. Próximo passo

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 A para o IPv4 da VPS: builder.example.com (editor do Typebot), bot.example.com (viewer do Typebot) e api.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.

Arquitetura do Typebot e da Evolution API na mesma VPS com Caddy nas portas 80 e 443 e chamadas internas para typebot-viewer na porta 3000

Preparar os arquivos

Crie a pasta do projeto. O nome dela vira o prefixo dos volumes no Docker:

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

Segredos 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:

bash
openssl rand -base64 24 | tr -d '\n' ; echo
openssl rand -hex 16

Rode 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:

.env
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_db

Restrinja a leitura do arquivo:

bash
chmod 600 .env

Pontos que evitam erro logo na primeira subida:

  • TYPEBOT_ENCRYPTION_SECRET precisa 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_EMAIL libera o plano UNLIMITED no workspace assim que você cria a conta com esse e-mail, evitando o limite de 200 chats do plano FREE.
  • 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_ID e GOOGLE_AUTH_CLIENT_SECRET (callback em https://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:

Caddyfile
{
	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:

docker-compose.yml
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.example da Evolution API o valor padrão é false. Sem ligar essa chave, toda chamada em /typebot/* devolve 400 Bad Request com Typebot is disabled.
  • TYPEBOT_API_VERSION: latest: faz a Evolution API usar as rotas atuais do Typebot (/api/v1/typebots/<slug>/startChat e /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:

bash
cd ~/typebot-whatsapp
sudo docker compose up -d
sudo docker compose ps

Na 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:

bash
sudo docker compose logs -f typebot-builder typebot-viewer evolution-api

Confira os três endereços com HTTPS válido:

bash
curl -fsS -I https://builder.example.com
curl -fsS -I https://bot.example.com
curl -fsS https://api.example.com

O 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

  1. Abra https://builder.example.com e faça login com o e-mail definido em TYPEBOT_ADMIN_EMAIL.
  2. Crie um fluxo novo (por exemplo, um menu de atendimento com um bloco de boas-vindas e uma pergunta de escolha).
  3. Clique em Publish no topo direito. Um fluxo em rascunho não responde na API do Viewer.
  4. Na aba Share, copie o identificador público do bot (o slug que aparece depois de https://bot.example.com/, por exemplo atendimento-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:

bash
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:

bash
cd ~/typebot-whatsapp
set -a && . ./.env && set +a

1. 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):

bash
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:

bash
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:

bash
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:

bash
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:

bash
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, apiKey e ownerJid: 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:

bash
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/instances

Copie 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:

bash
cd ~/typebot-whatsapp
sudo docker compose pull
sudo docker compose up -d

Trocar versão principal do PostgreSQL (16 ou 15) exige dump e restauração, não apenas troca de tag.

Próximo passo