Evolution API: guia completo de instalação em VPS Linux

A Evolution API consolidou-se como uma das soluções open-source mais adotadas para integrar o WhatsApp em automações empresariais. Diferente de APIs oficiais que exigem aprovação e custos recorrentes, ela opera via conexão direta com o cliente WhatsApp Web.

O desafio está na instalação: rodar a API exige conhecimento em Linux, Docker e configuração de proxy reverso. Este guia cobre o processo completo em um ambiente de produção.

Pré-requisitos de infraestrutura

Antes de iniciar, o servidor precisa atender aos requisitos mínimos de hardware e software.

Especificações recomendadas:

• 2 vCPUs e 2 GB RAM (mínimo); 4 GB para múltiplas instâncias simultâneas
• 20 GB de armazenamento SSD
• Ubuntu 22.04 LTS ou Debian 12
• Docker Engine 24.0+ e Docker Compose 2.x
• Porta 8080 liberada no firewall (ou a porta customizada escolhida)

A Evolution API consome cerca de 300-500 MB de RAM por instância ativa do WhatsApp. Planeje a capacidade conforme o número de conexões simultâneas esperadas.

Um domínio apontado para o IP do servidor é essencial caso a intenção seja expor a API via HTTPS com certificado SSL válido.

Instalação via Docker Compose

O método mais estável e recomendado pela comunidade é utilizar Docker Compose. Isso isola a aplicação, facilita atualizações e simplifica o gerenciamento de dependências.

Passo 1: preparar o ambiente

Acesse o servidor via SSH e atualize os pacotes base:

sudo apt update && sudo apt upgrade -y
sudo apt install curl git -y

Instale o Docker Engine e o Docker Compose seguindo a documentação oficial. Verifique a instalação:

docker --version
docker compose version

Passo 2: clonar o repositório oficial

A Evolution API mantém templates prontos no GitHub:

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

Passo 3: configurar variáveis de ambiente

Copie o arquivo de exemplo e edite conforme o ambiente:

cp .env.example .env
nano .env

Variáveis críticas a definir:

• API_KEY: token de autenticação para todas as requisições (gere uma string aleatória forte)
• AUTHENTICATION_API_KEY: chave adicional para endpoints administrativos
• DATABASE_PROVIDER: escolha entre postgresql, mysql ou sqlite (PostgreSQL recomendado para produção)
• DATABASE_CONNECTION_URI: string de conexão do banco escolhido
• WEBHOOK_GLOBAL_URL: endpoint que receberá eventos de mensagens (opcional, mas essencial para automações)

Deixe SERVER_URL vazio caso esteja atrás de um proxy reverso; caso contrário, informe o domínio público.

Passo 4: subir os containers

Com as variáveis configuradas, execute:

docker compose up -d

O comando baixa as imagens necessárias e inicia os serviços em segundo plano. Acompanhe os logs para confirmar que não há erros:

docker compose logs -f evolution-api

A API estará acessível na porta 8080 por padrão. Teste localmente:

curl http://localhost:8080

Se retornar JSON com informações da API, a instalação básica está completa.

Configurar proxy reverso com Nginx e SSL

Expor a porta 8080 diretamente na internet não é recomendado por questões de segurança. O padrão é usar Nginx como proxy reverso e adicionar certificado SSL via Let's Encrypt.

Instalar Nginx e Certbot

sudo apt install nginx certbot python3-certbot-nginx -y

Criar configuração de virtual host

Crie um arquivo no diretório de sites disponíveis:

sudo nano /etc/nginx/sites-available/evolution-api

Insira o bloco básico:

server {
    listen 80;
    server_name seu-dominio.com.br;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Ative o site e reinicie o Nginx:

sudo ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Emitir certificado SSL

sudo certbot --nginx -d seu-dominio.com.br

O Certbot configura automaticamente o redirecionamento HTTPS e renova o certificado a cada 90 dias.

Conectar a primeira instância do WhatsApp

Com a API rodando, use um cliente HTTP (Postman, Insomnia ou cURL) para criar uma instância.

Endpoint:

POST https://seu-dominio.com.br/instance/create

Headers:

apikey: SUA_API_KEY_AQUI

Body (JSON):

{
  "instanceName": "empresa01",
  "qrcode": true,
  "integration": "WHATSAPP-BAILEYS"
}

A resposta inclui um QR Code em base64. Escaneie-o pelo WhatsApp do smartphone (opção "Aparelhos conectados") para vincular.

Uma vez conectado, a instância permanece ativa enquanto o container estiver rodando. Quedas inesperadas exigem nova leitura de QR Code.

Erros comuns e troubleshooting

"Connection refused" ao acessar a API:

• Verifique se o container está rodando: docker ps
• Confirme que a porta 8080 não está ocupada: sudo lsof -i :8080

QR Code expira antes de escanear:

• Aumente o timeout na variável QRCODE_LIMIT no .env (padrão: 30 segundos)

Instância desconecta frequentemente:

• Pode indicar RAM insuficiente ou problemas de rede. Monitore com docker stats
• Ative logs detalhados alterando LOG_LEVEL para debug

Webhook não recebe eventos:

• Confirme que WEBHOOK_GLOBAL_URL está acessível externamente
• Teste com curl -X POST URL_DO_WEBHOOK -d '{"test":true}'

Trade-offs e considerações de produção

A Evolution API não é uma solução oficial do WhatsApp. Isso traz vantagens (custo zero, controle total), mas também riscos:

• Banimentos: contas que enviam spam ou mensagens em massa podem ser bloqueadas pelo WhatsApp
• Estabilidade: atualizações do WhatsApp Web eventualmente quebram a compatibilidade, exigindo updates frequentes da API
• Compliance: para uso comercial em larga escala, avalie se a API oficial do WhatsApp Business não atende melhor

Mantenha backups regulares do banco de dados e monitore logs para detectar anomalias precocemente.

Próximos passos

Com a Evolution API instalada e configurada, o próximo passo é integrá-la aos sistemas internos: CRMs, ERPs, chatbots ou automações serverless.

Na Rollin Host, oferecemos VPS otimizadas para aplicações Node.js e Docker, com suporte técnico para troubleshooting de instalações como esta. Entre em contato para discutir a infraestrutura ideal para o volume de mensagens do seu projeto.