Evolution API: Deploy Docker em VPS Ubuntu (Passo a Passo)

O que é a Evolution API e por que hospedá-la?

A Evolution API se estabeleceu como uma das principais ferramentas de integração do WhatsApp para empresas e desenvolvedores que desejam automatizar suas comunicações. Ao contrário das soluções oficiais do WhatsApp Business API que podem ser complexas e caras, a Evolution API oferece uma alternativa self-hosted, permitindo que você tenha controle total sobre seus dados e infraestrutura. Hospedar a Evolution API significa ter a liberdade de customizar, escalar e integrar com quaisquer outros sistemas, como CRMs, plataformas de e-commerce ou ferramentas de automação como o N8N.

Neste artigo, focaremos na implantação prática da Evolution API em um ambiente de servidor. Se você já decidiu que a Evolution API é a solução ideal para suas necessidades de WhatsApp API e criação de chatbot, o próximo passo é garantir um servidor robusto e confiável. Vamos guiá-lo através do processo de instalação usando Docker em um VPS Ubuntu, desde os requisitos básicos até a configuração final.

Por que Self-Hosted com Docker?

Optar por uma solução self-hosted como a Evolution API, especialmente quando combinada com Docker, traz inúmeras vantagens. O Docker simplifica o gerenciamento de dependências e a portabilidade da aplicação. Você pode executar a Evolution API em praticamente qualquer ambiente Linux compatível com Docker, garantindo que sua infraestrutura seja consistente e fácil de replicar. Isso é crucial para ambientes de produção onde estabilidade e previsibilidade são fundamentais. Além disso, o Docker isola a Evolution API de outras aplicações em seu servidor, evitando conflitos de bibliotecas e facilitando atualizações e rollbacks.

Requisitos de Servidor para Evolution API

Para rodar a Evolution API de forma eficiente em produção, especialmente se você planeja lidar com um volume considerável de mensagens ou múltiplos números de WhatsApp, um servidor bem configurado é essencial. A escolha do plano de hospedagem impactará diretamente a performance e a capacidade de resposta do seu sistema.

Recursos Mínimos e Recomendados

Com base em minha experiência ajudando clientes a configurar suas soluções de automação, posso afirmar que um ambiente básico para testes pode funcionar com recursos limitados, mas para produção, é recomendado o seguinte:

• RAM: Mínimo de 2GB. Para cargas de trabalho moderadas a altas, 4GB ou mais é recomendado. Um único container da Evolution API pode consumir entre 200MB e 600MB em repouso, dependendo da configuração e do número de instâncias de WhatsApp conectadas. Sob carga, esse consumo pode aumentar significativamente.
• CPU: Mínimo de 2 vCPUs. Mais núcleos de processamento beneficiam a resposta rápida de requisições e o processamento de eventos.
• Armazenamento: Mínimo de 20GB de espaço em disco. Isso considera o sistema operacional, o Docker, as imagens da Evolution API e seus bancos de dados (se você optar por persistência local). Recomenda-se SSD para melhor performance de I/O.

Portas Essenciais para Comunicação

A Evolution API utiliza algumas portas padrão para comunicação. É fundamental garantir que essas portas estejam abertas no firewall do seu servidor:

• 8080: Porta padrão para a API REST da Evolution API.
• 8000: Porta padrão para Webhooks (recebimento de eventos do WhatsApp).
• Outras portas podem ser usadas dependendo da configuração específica dos containers Docker, especialmente se você estiver executando múltiplos serviços ou usando configurações personalizadas.

A ausência de recursos adequados pode levar a lentidão, falhas na entrega de mensagens e instabilidade geral do serviço. É por isso que a Host You Secure oferece planos otimizados para este tipo de aplicação.

Tutorial de Instalação da Evolution API com Docker Compose

Implantar a Evolution API usando Docker Compose é a maneira mais eficiente e recomendada. Este método garante que todos os componentes necessários (API, banco de dados, etc.) sejam configurados e executados de forma organizada e isolada.

Passo 1: Preparando o Servidor Ubuntu

Primeiro, certifique-se de que seu servidor Ubuntu esteja atualizado. Acesse seu VPS via SSH e execute os seguintes comandos:

sudo apt update && sudo apt upgrade -y

Em seguida, instale o Docker e o Docker Compose. Se você já possui o Docker instalado, pode pular esta etapa. Para a instalação mais recente e recomendada, siga estas instruções:

# Instalar Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Adicionar usuário ao grupo docker (para não precisar usar sudo)
sudo usermod -aG docker $USER
newgrp docker

# Instalar Docker Compose
LATEST_COMPOSE=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d\" -f4)
sudo curl -L "https://github.com/docker/compose/releases/download/${LATEST_COMPOSE}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Passo 2: Criando o Arquivo Docker Compose

Agora, crie um diretório para sua aplicação Evolution API e navegue até ele. Dentro deste diretório, crie um arquivo chamado docker-compose.yml. Este arquivo definirá os serviços necessários para rodar a Evolution API.

Crie o arquivo docker-compose.yml e cole o seguinte conteúdo. É fundamental configurar as variáveis de ambiente corretamente, especialmente as chaves de API e segredos.

version: '3.8'

services:
  evolution-api:
    image: evolution-api/evolution-api:latest
    container_name: evolution-api
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "8000:8000"
    volumes:
      - ./data:/app/backend/src/data
      - ./logs:/app/backend/logs
    environment:
      - NODE_ENV=production
      - PORT=8080
      - WEBHOOK_PORT=8000
      - LOG_LEVEL=info
      - LOG_FILE=./logs/evolution-api.log
      - SESSION_FILE_PATH=./data/sessions
      - SESSION_IMPORT_PATH=./data/import
      - MULTIPLE_INSTANCES=true
      # Para banco de dados, se necessário (opcional, pode usar o sistema de arquivos por padrão)
      # - DB_TYPE=mongo
      # - DB_HOST=mongodb
      # - DB_PORT=27017
      # - DB_NAME=evolution
      # - DB_USER=user
      # - DB_PASS=password
      # Para autenticação da API
      - API_KEY=SUA_API_KEY_SECRETA_AQUI
      - API_SECRET=SEU_API_SECRET_AQUI

  # Se você usar MongoDB como banco de dados, descomente e configure este serviço
  # mongodb:
  #   image: mongo:latest
  #   container_name: evolution-mongodb
  #   restart: unless-stopped
  #   volumes:
  #     - ./db/mongo:/data/db
  #   environment:
  #     - MONGO_INITDB_ROOT_USERNAME=user
  #     - MONGO_INITDB_ROOT_PASSWORD=password
  #     - MONGO_INITDB_DATABASE=evolution

volumes:
  data:
  logs:
  # db:
  #   driver: local

Observações importantes sobre o docker-compose.yml:

• Substitua SUA_API_KEY_SECRETA_AQUI e SEU_API_SECRET_AQUI por chaves fortes e únicas. Essas chaves são usadas para proteger o acesso à sua API.
• Os volumes ./data e ./logs são criados no diretório onde o docker-compose.yml está localizado para persistir os dados de sessão e os logs.
• Se você pretende usar MongoDB, descomente a seção do serviço mongodb e ajuste as variáveis de ambiente no serviço evolution-api para que apontem para ele.
• A porta 8080 é exposta para a API principal e a 8000 para os webhooks.

Passo 3: Iniciando os Containers

Com o arquivo docker-compose.yml configurado, você pode iniciar os containers com o seguinte comando:

docker-compose up -d

O comando -d inicia os containers em modo detached (em segundo plano). Se você quiser ver os logs em tempo real, remova o -d.

Passo 4: Acessando a Evolution API

Após os containers iniciarem (pode levar alguns minutos na primeira vez para baixar as imagens), você poderá acessar a API em http://SEU_IP_DO_SERVIDOR:8080. Para gerenciar suas instâncias de WhatsApp, é comum utilizar a interface web da Evolution API (geralmente acessada em outra porta, dependendo da configuração) ou interagir diretamente via API REST.

Para verificar o status dos seus containers, utilize:

docker ps

Configurando um Chatbot Simples

Com a Evolution API rodando, o próximo passo é configurar um chatbot. A maneira mais comum de fazer isso é configurar os webhooks. Quando uma nova mensagem chega no número de WhatsApp conectado, a Evolution API enviará uma notificação (um POST request) para a URL do seu webhook configurado.

Webhook e Integração

Você pode criar um serviço separado (ou usar uma ferramenta como N8N, que também pode ser hospedada em seu VPS) que escute na porta 8000 (ou outra porta configurada para webhooks) e processe essas mensagens. Por exemplo, seu webhook pode receber uma mensagem, verificar seu conteúdo e, com base em regras predefinidas, enviar uma resposta de volta usando a Evolution API.

Exemplo de como enviar uma mensagem de volta via API (usando cURL para demonstrar):

curl -X POST "http://SEU_IP_DO_SERVIDOR:8080/message/send-text/SEU_INSTANCE_NAME"
     -H "Content-Type: application/json"
     -H "apiKey: SUA_API_KEY_SECRETA_AQUI"
     -d '{
       "number": "NUMERO_DO_DESTINATARIO",
       "message": ["Olá! Esta é uma resposta automática do seu chatbot."]
     }'

Onde SEU_INSTANCE_NAME é o nome da instância que você definiu (ou que o Docker gerou automaticamente se não especificado), NUMERO_DO_DESTINATARIO é o número de telefone completo com código do país, e SUA_API_KEY_SECRETA_AQUI é a chave que você definiu no seu docker-compose.yml.

Tabelas de Comparação: Evolution API vs. Outras Soluções

Erros Comuns e Soluções

Ao configurar a Evolution API, alguns problemas são recorrentes. Conhecê-los pode economizar muito tempo de depuração.

• Problema: Falha ao conectar o número do WhatsApp.
  Solução: Verifique se as portas 8080 e 8000 estão abertas no firewall do seu VPS. Certifique-se de que o QR code gerado está sendo escaneado dentro do tempo limite e que o navegador usado para escanear está limpo (sem extensões que possam interferir). Verifique os logs da Evolution API para mensagens de erro detalhadas.
• Problema: Webhooks não recebem mensagens.
  Solução: Confirme se a URL do webhook está corretamente configurada na interface de gerenciamento da Evolution API e se ela aponta para o IP público do seu servidor e a porta correta (ex: http://seu-ip:8000/webhook). Certifique-se de que o container que recebe os webhooks está rodando e acessível.
• Problema: API lenta ou não responde.
  Solução: Verifique os recursos do seu servidor (CPU e RAM). Um VPS subdimensionado é a causa mais comum. Monitore o consumo de recursos com docker stats. Considere um upgrade para um plano com mais RAM e CPU.
• Problema: Múltiplas instâncias não funcionam juntas.
  Solução: Verifique se a variável MULTIPLE_INSTANCES está definida como true no seu docker-compose.yml. Garanta que os volumes para persistência de dados (como sessões) estão configurados corretamente para cada instância, se necessário, ou use um banco de dados centralizado.

Perguntas Relacionadas (People Also Ask)

Aqui respondemos algumas dúvidas comuns que surgem durante o processo de implantação e uso da Evolution API.

Qual a diferença entre Evolution API e a API oficial do WhatsApp?

A principal diferença reside no modelo de hospedagem e controle. A Evolution API é uma solução self-hosted, onde você gerencia o servidor e a aplicação, oferecendo total flexibilidade. A API oficial do WhatsApp (WhatsApp Business Platform) é uma solução baseada em nuvem oferecida pela Meta, com aprovação e suporte oficial, mas com menos controle sobre a infraestrutura e potencial custo associado a cada mensagem enviada.

É seguro usar a Evolution API?

Sim, a Evolution API é considerada segura quando configurada corretamente. Ela utiliza os protocolos oficiais do WhatsApp para conexão (via navegador headless) e suas chaves de API protegem o acesso à sua instância. No entanto, a segurança da sua implementação depende da sua própria infraestrutura, como a proteção do seu VPS com firewall e a configuração de senhas fortes.

Posso usar a Evolution API com múltiplos números de WhatsApp?

Sim, a Evolution API suporta múltiplas instâncias, permitindo que você gerencie vários números de telefone em um único servidor. Isso é configurado através da variável MULTIPLE_INSTANCES=true no Docker Compose e definindo configurações específicas para cada número.

Quanto custa rodar a Evolution API?

O custo principal é o do servidor onde você irá hospedá-la. Planos VPS como o VPS Brasil Starter da Host You Secure, que oferece 2GB de RAM e 2 vCPUs a partir de R$ 49/mês, são um excelente ponto de partida. Além disso, pode haver custos associados a serviços adicionais como bancos de dados ou ferramentas de monitoramento, se você decidir utilizá-los.

Conclusão e Próximos Passos

Hospedar a Evolution API em um VPS Ubuntu com Docker é uma abordagem poderosa para quem busca uma solução de WhatsApp API flexível e escalável. Seguindo este guia, você terá um ambiente pronto para criar chatbots, automatizar mensagens e integrar o WhatsApp em seus sistemas de forma controlada.

A chave para o sucesso é um servidor bem dimensionado e uma configuração cuidadosa. Para começar, recomendo o plano VPS Brasil Starter da Host You Secure. Ele oferece 2GB de RAM e 2 vCPUs por apenas R$ 49/mês, sendo ideal para rodar esse exato setup da Evolution API com Docker. Você terá a performance necessária sem custos excessivos.

Comece hoje mesmo a automatizar suas comunicações no WhatsApp! Explore as possibilidades da Evolution API e leve seu atendimento e marketing para o próximo nível. Se precisar de ajuda com a configuração ou escolher o plano ideal, nossa equipe está à disposição.

Pronto para dar o próximo passo? Adquira seu VPS Brasil Starter e comece sua jornada de automação!

Leia também: Veja mais tutoriais de N8N