Índice do artigo
Resolvendo Erros Comuns na Evolution API: Guia de Implantação e Troubleshooting
A Evolution API, quando rodando em seu próprio servidor VPS, oferece controle total e escalabilidade para suas automações WhatsApp. No entanto, como qualquer software self-hosted, você pode encontrar desafios. Este guia foca em como implantar a Evolution API em um VPS Ubuntu, detalhando a solução para problemas como evolution api desconectando sozinha, evolution api não envia mensagem, erro ao criar instância evolution api e evolution api webhook não dispara. Assumimos que você já decidiu utilizar a Evolution API e agora precisa de um ambiente estável para rodá-la. Para um funcionamento robusto, recomendamos um servidor com no mínimo 4GB de RAM e 4 vCPUs, como o nosso plano VPS Brasil Básico, que nossos clientes utilizam com sucesso para esta stack.
Veja a infraestrutura: VPS para n8n + Evolution API para colocar este projeto no ar.
Passo a Passo: Implantação da Evolution API em VPS Ubuntu
Implantar a Evolution API em um VPS com Ubuntu é um processo direto, especialmente quando utilizamos Docker e Docker Compose. Esta abordagem garante isolamento, facilidade de gerenciamento e atualizações mais limpas. Para um ambiente de produção, além da Evolution API, você também precisará de um banco de dados (geralmente PostgreSQL) e um proxy reverso (Nginx é uma escolha comum) para gerenciar conexões e certificados SSL.
1. Pré-requisitos no Servidor
Antes de iniciar a instalação, certifique-se de que seu servidor VPS atende aos requisitos mínimos e que as ferramentas essenciais estão instaladas. Para a Evolution API rodar de forma estável em produção, com banco de dados e proxy, recomendamos:
- RAM: Mínimo de 4GB. Para mais de 10 instâncias ou alto volume de mensagens, 8GB ou mais são ideais.
- CPU: Mínimo de 4 vCPUs.
- Armazenamento: Mínimo de 30GB SSD, com espaço adicional para logs e backups.
- Sistema Operacional: Ubuntu 20.04 LTS ou superior.
- Software Essencial: Docker e Docker Compose (versão plugin).
Para instalar o Docker e o Docker Compose plugin no Ubuntu, execute os seguintes comandos:
# Atualizar lista de pacotes
sudo apt update
# Instalar pacotes necessários
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
# Adicionar chave GPG oficial do Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# Adicionar repositório Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Instalar Docker Engine e Docker Compose Plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Verificar instalação
docker --version
docker compose version
2. Configuração do Docker Compose
Crie um diretório para a sua aplicação Evolution API e, dentro dele, crie o arquivo docker-compose.yml. Este arquivo definirá os serviços necessários: a Evolution API e um banco de dados PostgreSQL. Para garantir que a Evolution API funcione corretamente, é crucial que o banco de dados esteja configurado e acessível antes da API iniciar.
version: '3.8'
services:
evolution-api:
image: revolutoin/evolution-api:latest
container_name: evolution-api
restart: unless-stopped
ports:
- "5000:5000"
environment:
NODE_ENV: "production"
PORT: "5000"
API_URL: "http://localhost:5000"
TOKEN_APP: "SEU_TOKEN_SEGURO_AQUI"
DATABASE_URL: "postgresql://user:password@db:5432/evolution_api"
WEBHOOK_URL: "https://seu-dominio.com/webhook"
# Outras variáveis de ambiente podem ser necessárias dependendo da sua configuração
depends_on:
- db
volumes:
- evolution-data:/usr/src/app/files
db:
image: postgres:14
container_name: evolution-api-db
restart: unless-stopped
environment:
POSTGRES_DB: "evolution_api"
POSTGRES_USER: "user"
POSTGRES_PASSWORD: "password"
ports:
- "5432:5432"
volumes:
- evolution-db-data:/var/lib/postgresql/data
volumes:
evolution-data:
evolution-db-data:
Atenção: Substitua SEU_TOKEN_SEGURO_AQUI por um token forte e único. Ajuste user, password e evolution_api no DATABASE_URL para corresponder às credenciais e nome do banco de dados que você definir para o serviço db. O WEBHOOK_URL deve apontar para o endpoint público onde você deseja receber os eventos. A porta 5000 é a padrão da Evolution API. Para produção, é recomendado expor a API através de um proxy reverso como Nginx, que cuidará da porta 80/443 e SSL.
3. Executando a Aplicação
Navegue até o diretório onde você salvou o arquivo docker-compose.yml e execute o seguinte comando para subir os containers:
docker compose up -d
O flag -d executa os containers em modo detached (background). Para verificar o status dos containers, use:
docker compose ps
E para ver os logs em tempo real, especialmente em caso de problemas:
docker compose logs -f evolution-api
docker compose logs -f db
Resolver problemas como erro ao criar instância evolution api geralmente envolve verificar os logs do container evolution-api e do container db para identificar falhas de conexão ou configuração.
Troubleshooting: Evolução API Desconectando Sozinha e Não Enviando Mensagens
Quando a evolution api desconecta sozinha, as causas mais comuns são:
- Recursos Insuficientes: Falta de RAM ou CPU no servidor VPS. Um servidor com menos de 4GB de RAM pode ter o container da Evolution API ou do banco de dados encerrado pelo sistema operacional (OOM Killer).
- Problemas de Rede: Instabilidade na conexão entre o VPS e os servidores do WhatsApp.
- Configurações Incorretas: Variáveis de ambiente mal configuradas no
docker-compose.ymlou no arquivo.env, como tokens inválidos ou URLs incorretas. - Versão Desatualizada: Bugs em versões mais antigas da Evolution API. Mantenha sempre a imagem mais recente ou uma versão estável conhecida.
Para a questão de evolution api não envia mensagem:
- Instância Desconectada: A instância do WhatsApp pode ter se desconectado. Verifique o status da instância através da API ou do dashboard.
- Token Inválido: O token de autenticação da API pode ter expirado ou sido revogado.
- Rate Limiting: O WhatsApp pode estar limitando o envio de mensagens se um volume muito alto for enviado em curtos períodos.
- Formato da Mensagem: Erros na formatação dos dados enviados na requisição de envio de mensagem (ex: número de telefone no formato incorreto, tipo de mídia não suportado).
Se você está enfrentando problemas persistentes, considere consultar nosso artigo sobre Evolution API: Erros Comuns e Soluções VPS para um aprofundamento em cenários específicos.
Configurando Webhooks e Tratando Erros de Instância
O evolution api webhook não dispara é uma queixa frequente. As causas mais comuns incluem:
- URL do Webhook Incorreta: Verifique se a
WEBHOOK_URLconfigurada no ambiente da Evolution API está correta, acessível publicamente e se não há erros de digitação. - Firewall Bloqueando: O firewall do seu VPS ou do servidor onde o webhook está hospedado pode estar bloqueando a conexão de entrada na porta configurada (geralmente 80 ou 443).
- Certificado SSL Inválido: Se você usa HTTPS para o webhook, um certificado SSL inválido ou expirado impedirá que a Evolution API se conecte.
- Lógica do Webhook: O próprio endpoint do webhook pode estar com erros, não respondendo corretamente ou demorando demais para processar a requisição, levando a um timeout. Teste seu endpoint com ferramentas como Postman.
- Erro ao Criar Instância: Se a instância não foi criada corretamente, os webhooks associados a ela não dispararão. Verifique os logs de criação da instância. Um erro ao criar instância evolution api pode estar diretamente ligado à configuração do banco de dados ou a problemas de rede que impedem a comunicação com os servidores do WhatsApp.
Para garantir que sua infraestrutura de automação seja robusta, é fundamental ter um servidor confiável. Ferramentas como o N8N, que podem ser integradas com a Evolution API, também requerem uma configuração adequada. Se você ainda não configurou o proxy reverso, veja este guia para entender como um bom setup de rede pode evitar muitos problemas.
Comparativo: Requisitos de Servidor para Evolution API
Escolher o VPS correto é crucial para a estabilidade da Evolution API. Abaixo, uma comparação dos requisitos típicos:
| Componente | Ambiente de Desenvolvimento/Teste | Produção (1-5 Instâncias) | Produção (5-15 Instâncias) |
|---|---|---|---|
| RAM | 2GB | 4GB | 8GB+ |
| vCPUs | 2 | 4 | 6+ |
| Armazenamento (SSD) | 15GB | 30GB+ | 50GB+ |
| Banco de Dados | Pode ser compartilhado ou em contêiner separado | Contêiner dedicado (PostgreSQL recomendado) | Contêiner dedicado ou instância gerenciada |
| Proxy Reverso | Opcional | Nginx/Caddy (essencial para produção) | Nginx/Caddy (essencial) |
| Consumo Típico (API ociosa) | ~200MB RAM | ~300-500MB RAM | ~600-800MB RAM |
Note que o consumo de RAM listado para a API é apenas para o contêiner da aplicação em si. O consumo total do servidor incluirá o sistema operacional, o banco de dados, o proxy reverso e outros serviços. Por isso, para produção com 5 instâncias, 4GB de RAM no VPS total é um ponto de partida seguro, garantindo que todos os componentes tenham recursos suficientes.
Perguntas Relacionadas
Por que minha Evolution API está lenta?
A lentidão geralmente indica gargalos de recursos. Verifique o uso de CPU e RAM no seu VPS. Se estiverem constantemente altos, você pode precisar de um plano de VPS com mais recursos ou otimizar seu banco de dados e configurações da API. Uma rede instável entre o servidor e o WhatsApp também pode causar lentidão.
Como faço para atualizar a Evolution API?
Se você usou Docker Compose, o processo é simples: navegue até o diretório do seu docker-compose.yml, execute docker compose pull para baixar a nova imagem, e então docker compose up -d para reiniciar os contêineres com a versão atualizada. Verifique os logs após a atualização para garantir que tudo subiu corretamente.
O que fazer se a Evolution API não reconhece a conexão do WhatsApp?
Isso geralmente está ligado a problemas de instância. Verifique se o QR code foi escaneado corretamente, se o token de autenticação da API está válido e se não há bloqueios de rede impedindo a comunicação com os servidores do WhatsApp. Reiniciar a instância e os contêineres da Evolution API e do banco de dados pode resolver problemas temporários.
É seguro usar a Evolution API em um VPS compartilhado?
Embora tecnicamente possível, não é recomendado para ambientes de produção. Um VPS dedicado oferece mais segurança, isolamento de recursos e controle sobre a configuração. Em um VPS compartilhado, o desempenho e a segurança podem ser afetados por outros usuários.
Conclusão e Recomendação
A Evolution API é uma ferramenta poderosa, e com a configuração correta em um VPS robusto, você pode evitar a maioria dos problemas comuns. Desde a implantação inicial com Docker Compose até o troubleshooting de desconexões, mensagens não enviadas ou webhooks inativos, a chave está em monitorar os logs, garantir recursos adequados e configurar corretamente as variáveis de ambiente.
Para rodar a Evolution API com estabilidade e performance em produção, com banco de dados e proxy reverso, recomendamos o plano VPS Brasil Básico. Nossos clientes rodam essa mesma stack em uma VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs, ideal para iniciar suas automações WhatsApp de forma confiável. Não deixe que problemas técnicos atrasem suas operações.
Conheça o VPS Brasil Básico e garanta a estabilidade da sua operação hoje mesmo!
📦 Template n8n: Agente de IA com WhatsApp + Evolution API
Baixe o arquivo JSON pronto para importar: Webhook configurado, tratamento de remetente, nó de OpenAI e disparo via Evolution API.
FAQ: perguntas frequentes
Quais são os requisitos mínimos de RAM para rodar a Evolution API em produção?
Para um ambiente de produção com a Evolution API, banco de dados e proxy reverso, recomendamos um mínimo de 4GB de RAM. Este valor garante que o sistema operacional, os contêineres Docker e os serviços essenciais operem sem problemas. Para cenários com mais de 5 instâncias ou alto volume de mensagens, 8GB ou mais são aconselháveis para manter a performance e evitar instabilidade.
O que causa o erro 'erro ao criar instância evolution api'?
Este erro geralmente aponta para problemas na comunicação com os servidores do WhatsApp ou falhas na configuração do banco de dados. Verifique se o token de autenticação está correto, se a URL da API está acessível e se o PostgreSQL está rodando e acessível pela Evolution API. Revise os logs de ambos os contêineres (API e DB) para identificar a causa raiz.
Como resolver 'evolution api desconectando sozinha'?
A desconexão frequente pode ser causada por falta de recursos no servidor VPS (RAM insuficiente é a principal causa), instabilidade na rede, problemas de configuração (tokens, URLs) ou bugs em versões desatualizadas da API. Certifique-se de que seu VPS atende aos requisitos mínimos de 4GB RAM e 4 vCPUs para produção e que sua conexão com a internet é estável.
Por que meu 'evolution api webhook não dispara'?
Verifique se a <code>WEBHOOK_URL</code> configurada está correta, acessível publicamente e se o certificado SSL (se usar HTTPS) é válido. Certifique-se de que firewalls no seu VPS ou no servidor do webhook não estão bloqueando a requisição. Também é crucial que a instância da Evolution API esteja conectada e funcionando corretamente para que os eventos sejam enviados.
Qual a diferença entre rodar a Evolution API em desenvolvimento e produção?
Em desenvolvimento, você pode usar configurações mais simples e menos recursos (ex: 2GB RAM). Em produção, é essencial um ambiente robusto com recursos dedicados (mínimo 4GB RAM, 4 vCPUs), banco de dados separado, proxy reverso para segurança e alta disponibilidade, e monitoramento constante para garantir estabilidade e performance.
Como configurar o Nginx como proxy reverso para Evolution API?
Crie um arquivo de configuração no Nginx (ex: `/etc/nginx/sites-available/evolution-api`) definindo o `server_name` para seu domínio, e `proxy_pass` para `http://localhost:5000` (ou a porta onde a Evolution API está rodando). Ative o site, configure SSL e reinicie o Nginx. Isso protege sua API e permite acesso via `seudominio.com`.
É possível usar a Evolution API sem Docker?
Sim, é possível instalar a Evolution API diretamente no sistema operacional host. No entanto, usar Docker e Docker Compose é a abordagem recomendada para produção. Ela simplifica o gerenciamento de dependências, isola a aplicação, facilita atualizações e rollbacks, e garante um ambiente mais consistente e fácil de replicar.
O que o token `TOKEN_APP` na configuração da Evolution API faz?
O `TOKEN_APP` é uma chave de autenticação secreta que você define. Ela é usada para proteger o acesso à sua instância da Evolution API. Qualquer requisição feita à API deve incluir este token em um cabeçalho de autorização (ex: `Authorization: Bearer SEU_TOKEN_SEGURO_AQUI`). Isso garante que apenas aplicações autorizadas possam interagir com sua instância.