Como hospedar a Evolution API (WhatsApp)

A Evolution API transforma uma conta de WhatsApp em uma API REST. Seu sistema (CRM, chatbot, painel) manda um POST e a mensagem sai; quando chega mensagem, ela avisa por webhook. Por isso muita gente a usa no lugar de montar um bot do zero com uma biblioteca.

Hospedar é diferente de rodar no seu computador. A API mantém uma conexão aberta com o WhatsApp e guarda sessões e mensagens em banco. Se o processo cai, a conexão cai. Os passos abaixo seguem o README do repositório; confira as releases antes de instalar, porque scripts e variáveis podem mudar entre versões.

O que a Evolution API precisa para rodar?#

Segundo o README oficial:

• A versão LTS ativa do Node.js (se rodar sem Docker).
• PostgreSQL ou MySQL, escolhido em DATABASE_PROVIDER.
• Redis, recomendado para cache.
• Um processo que fique ligado o tempo todo, escutando a porta 8080 por padrão.

Há também uma imagem Docker, evoapicloud/evolution-api:latest. O repositório traz um docker-compose.yaml com a API, um Redis e um PostgreSQL.

Como subir com Docker Compose?#

Crie uma pasta com dois arquivos. Primeiro o .env, com valores seus (não use a chave de exemplo do repositório):

SERVER_PORT=8080
SERVER_URL=http://localhost:8080
AUTHENTICATION_API_KEY=troque-por-uma-chave-longa-e-aleatoria
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:troque-a-senha@postgres:5432/evolution_db?schema=evolution_api
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution
POSTGRES_DB=evolution_db
POSTGRES_USER=evolution
POSTGRES_PASSWORD=troque-a-senha

Depois o docker-compose.yaml, enxuto a partir do arquivo oficial:

services:
  api:
    image: evoapicloud/evolution-api:latest
    restart: always
    depends_on: [redis, postgres]
    ports:
      - "8080:8080"
    env_file: .env
    volumes:
      - evolution_instances:/evolution/instances

  redis:
    image: redis:latest
    restart: always
    command: redis-server --port 6379 --appendonly yes
    volumes:
      - evolution_redis:/data

  postgres:
    image: postgres:15
    restart: always
    env_file: .env
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:

Suba com docker compose up -d. O arquivo oficial publica a API só em 127.0.0.1; o exemplo acima a expõe em todas as interfaces, então coloque um proxy reverso com HTTPS na frente e nunca deixe a porta aberta sem a chave.

Como rodar sem Docker?#

Serve para ambientes que executam Node.js direto. Os passos do repositório são:

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
npm install
cp .env.example .env   # edite banco, Redis e AUTHENTICATION_API_KEY
npm run db:generate
npm run db:deploy
npm run build
npm run start:prod

O db:deploy aplica as migrations do provedor escolhido em DATABASE_PROVIDER, então defina essa variável antes. O start:prod executa o dist/main compilado.

O db:generate gera o cliente do Prisma para o provedor escolhido; sem ele, a API não sobe. Se o ambiente instala só as dependencies (com NODE_ENV=production), dois scripts quebram: o build, porque o tsc é devDependency, e o prepare, porque o husky também é. Nesse caso, compile em outro lugar e troque o prepare por husky || true, como sugere a documentação do Husky.

Como criar a instância e conectar o WhatsApp?#

Cada número de WhatsApp é uma instância. A chave global (AUTHENTICATION_API_KEY) vai no header apikey:

curl -X POST http://localhost:8080/instance/create \
  -H "apikey: $AUTHENTICATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"minha-instancia","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'

A resposta traz o QR code em qrcode.base64. Se precisar de outro, peça com GET /instance/connect/minha-instancia. No celular, abra o WhatsApp, vá em Aparelhos conectados, Conectar um aparelho e leia o código. Depois confira o estado:

curl http://localhost:8080/instance/connectionState/minha-instancia \
  -H "apikey: $AUTHENTICATION_API_KEY"

Como enviar a primeira mensagem?#

curl -X POST http://localhost:8080/message/sendText/minha-instancia \
  -H "apikey: $AUTHENTICATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","text":"Olá da Evolution API"}'

O number leva o código do país e o DDD, sem +. Se a resposta trouxer os dados da mensagem enviada e o texto chegar no celular, deu certo. Para receber mensagens, configure o webhook da instância apontando para uma URL sua.

Como proteger a instalação?#

A AUTHENTICATION_API_KEY dá acesso total: cria e apaga instâncias e envia mensagens por qualquer número conectado. Trate-a como uma senha de produção.

• Gere uma chave longa e aleatória e guarde em variável de ambiente, nunca no repositório (veja o que são variáveis de ambiente).
• Não exponha o PostgreSQL nem o Redis na internet. No Compose, deixe-os só na rede interna e remova qualquer ports desses serviços.
• Sirva a API atrás de HTTPS e, se possível, limite por IP quem chama.
• Troque SERVER_URL pela URL pública real, porque ela aparece nas respostas e nos webhooks.
• Se quiser entender melhor o empacotamento, leia como dockerizar uma aplicação.

A Evolution API é um projeto de terceiros: acompanhe as releases do repositório antes de trocar a tag da imagem, em vez de depender sempre de latest.

Quais erros são comuns?#

• Falha ao conectar no banco: DATABASE_CONNECTION_URI com host errado. Dentro do Compose o host é o nome do serviço (postgres), não localhost.
• Migrations não rodaram: em instalação sem Docker, faltou npm run db:deploy ou a variável DATABASE_PROVIDER.
• Erro de TLS no banco: se o banco exige certificado de cliente, o Prisma o lê na própria DATABASE_CONNECTION_URI: sslmode=require, sslcert com a CA do servidor e sslidentity com o certificado do cliente em PKCS12 (mais sslpassword, se houver). Os caminhos são relativos à pasta prisma.
• redis disconnected em loop com rediss://: o cliente redis da Evolution API liga o TLS sozinho com rediss://, mas só confia nas CAs públicas. Se o Redis usa CA própria, aponte NODE_EXTRA_CA_CERTS para o arquivo da CA no comando que inicia o processo, não no .env: o Node só lê essa variável ao iniciar.
• 401 nas chamadas: o header apikey não bate com AUTHENTICATION_API_KEY.
• QR code pedido de novo após reiniciar: os dados da instância não persistiram. Confira volumes e banco, e leia por que o bot de WhatsApp desconecta.
• Número restringido: a integração Baileys não é oficial. Para uso comercial em escala, compare com a API oficial.

Como fazer isso na Square Cloud#

A Evolution API precisa ficar online o tempo todo. Na Square Cloud, uma hospedagem self-service, os containers ficam sempre ligados, sem modo de suspensão, e o reinício automático, que vem ligado no deploy pelo painel, traz o processo de volta quando ele encerra com erro.

Você roda a Evolution API no runtime Node.js, com a instalação a partir do código-fonte descrita acima. Não há Dockerfile, Docker Compose nem etapa de build, e as dependências são instaladas com NODE_ENV=production: compile num CI externo, como o GitHub Actions, envie o projeto já com a pasta dist e ajuste o prepare como descrito acima. Como a Evolution API lê a porta de SERVER_PORT, um START como npm run db:generate && npm run db:deploy && SERVER_PORT=$PORT npm run start:prod faz a API escutar na porta da variável PORT, que a plataforma define.

As variáveis de ambiente são por aplicação: o painel importa um .env, e a mudança vale no próximo restart. A partir do plano Standard, você hospeda PostgreSQL, MySQL e Redis no mesmo datacenter das aplicações; o Hobby não inclui banco. O painel entrega a URL de conexão completa e o certificado, e o TLS é obrigatório. No PostgreSQL, o cliente também apresenta o certificado baixado, configurado na URL como explicado nos erros comuns, acima. A RAM do plano é um pool compartilhado, com mínimo de 512 MB por aplicação web.

Para usar um Redis hospedado na plataforma como cache, baixe na página do banco a opção Certificate CA (.crt), que salva o ca-certificate.crt, coloque o arquivo na raiz do projeto e defina:

# variáveis de ambiente da aplicação (a URL de conexão do painel)
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=rediss://default:SUA_SENHA@HOST:PORTA
# comando START
npm run db:generate && npm run db:deploy && NODE_EXTRA_CA_CERTS=./ca-certificate.crt SERVER_PORT=$PORT npm run start:prod

Use o host da URL do painel, não um IP, para o nome bater com o certificado, e não acrescente /6: esse Redis tem um único database lógico e não pede certificado de cliente.

Se preferir montar o bot direto com Baileys, WPPConnect, whatsapp-web.js ou a Cloud API oficial, veja a hospedagem de bots de WhatsApp.