# Typebot e Evolution API na mesma VPS para WhatsApp | Nuvits

Fonte: [https://nuvits.net/blog/typebot-evolution-api-whatsapp-vps](https://nuvits.net/blog/typebot-evolution-api-whatsapp-vps)

Publicado em 2026-11-20, por Fernando Chagas.

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.

As configurações abaixo seguem o repositório oficial do [Typebot `v3.19.1`](https://github.com/baptisteArno/typebot.io) e o código-fonte da [Evolution API `v2.3.7`](https://github.com/evolution-foundation/evolution-api), 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](https://nuvits.net/blog/como-instalar-evolution-api-docker-vps) e [n8n e Evolution API na mesma VPS](https://nuvits.net/blog/n8n-evolution-api-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](https://nuvits.net/blog/como-instalar-n8n-docker-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](https://docs.typebot.io/self-hosting/configuration) 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](https://nuvits.net/blog/typebot-evolution-api-whatsapp-vps/arquitetura-typebot-evolution-api-caddy.webp)

> **O Docker passa por cima do ufw.** Só o Caddy publica as portas 80 e 443. Builder, Viewer, Evolution API, PostgreSQL e Redis ficam sem `ports:`. O motivo e o teste de firewall estão em [A porta do Docker continua aberta com o ufw](https://nuvits.net/blog/porta-do-docker-aberta-com-ufw).

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

```ini .env
BUILDER_DOMAIN=builder.example.com
VIEWER_DOMAIN=bot.example.com
EVOLUTION_DOMAIN=api.example.com
ACME_EMAIL=voce@example.com

TYPEBOT_VERSION=3.19.1
TYPEBOT_ENCRYPTION_SECRET=cole-aqui-os-32-caracteres-base64
TYPEBOT_ADMIN_EMAIL=voce@example.com
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 <notificacoes@example.com>'
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](https://docs.typebot.io/self-hosting/configuration).

> **Guarde o `.env` fora da VPS.** Sem `TYPEBOT_ENCRYPTION_SECRET`, um backup restaurado do banco do Typebot não consegue abrir credenciais criptografadas. Sem `EVOLUTION_API_KEY`, as chamadas para a Evolution API falham.

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

```caddy 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:

```yaml 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](https://docs.typebot.io/self-hosting/guides/s3). 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 `5511999999999@s.whatsapp.net`).
- `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.

> **Nunca rode `docker compose down -v` nesta pasta.** A opção `-v` apaga todos os volumes: bancos do Typebot e da Evolution API, chaves e sessões do WhatsApp.

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

- 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](https://nuvits.net/blog/typebot-evolution-api-nao-responde).
- Para escolher o servidor dessa stack, veja [VPS para Evolution API](https://nuvits.net/vps-para-evolution-api) ou [VPS com Docker](https://nuvits.net/vps-docker).
