Índice do artigo
Desmistificando Erros na Evolution API: Seu Guia Completo
A Evolution API é uma ferramenta poderosa para integrar o WhatsApp Business em seus sistemas, mas como qualquer software complexo, ela pode apresentar desafios. Se você está enfrentando a evolution api desconectando sozinha, a evolution api não envia mensagem, ou até mesmo um erro ao criar instância evolution api, este artigo é para você. Vamos mergulhar nas causas mais comuns e apresentar soluções práticas, focando na implantação robusta em um ambiente de produção, como um VPS Linux.
Veja a infraestrutura: VPS para n8n + Evolution API para colocar este projeto no ar.
Para rodar a Evolution API de forma estável em produção, um servidor com no mínimo 4GB de RAM e 4 vCPUs é recomendado. Essa configuração garante que a aplicação, juntamente com seus contêineres de banco de dados e proxy reverso, opere sem interrupções, mesmo sob carga. A estabilidade da sua comunicação via WhatsApp depende diretamente da infraestrutura subjacente.
Diagnóstico e Solução de Erros Comuns na Evolution API
1. Evolução API Desconectando Sozinha: Causas e Correções
A desconexão inesperada da Evolution API pode ser um sintoma de diversos problemas. A causa mais frequente, em minha experiência, é a falta de recursos no servidor. Quando um VPS não possui RAM ou CPU suficientes, o sistema operacional pode, por conta própria, encerrar processos que consomem mais recursos para manter a estabilidade geral, e a Evolution API pode ser uma vítima.
Outras causas incluem:
- Problemas de Rede: Instabilidade na conexão entre o servidor e os servidores do WhatsApp. Verifique logs de rede e a conectividade geral do seu VPS.
- Configurações Incorretas: Parâmetros mal configurados no arquivo de ambiente (.env) ou no Docker Compose.
- Versões Desatualizadas: Utilizar versões antigas da Evolution API ou do Docker pode levar a bugs conhecidos.
- Limites de Rate: O WhatsApp pode impor limites de conexão temporários.
Para mitigar, certifique-se de que seu servidor atende aos requisitos mínimos de 4GB de RAM e 4 vCPUs. Monitore o uso de recursos com comandos como docker stats. Se o problema persistir, revise suas configurações e considere atualizar para a última versão estável da Evolution API.
2. Evolution API Não Envia Mensagem: O Que Fazer?
Quando a Evolution API falha ao enviar mensagens, o problema geralmente está na comunicação com a API do WhatsApp ou na configuração do seu lado. Verifique se a instância está ativa e conectada. Um erro comum é a má configuração do token de autenticação ou do número de telefone associado à instância.
Passos para depuração:
- Verifique os Logs: Acesse os logs da Evolution API (se estiver usando Docker, `docker logs
`) para mensagens de erro detalhadas. - Status da Instância: Consulte o status da instância via API. Se ela estiver desconectada ou em erro, resolva primeiro esse problema.
- Credenciais: Revise o arquivo `.env` e certifique-se de que `API_TOKEN` e `PHONE_NUMBER` estão corretos e correspondem à sua instância.
- API do WhatsApp: Em casos raros, pode haver uma instabilidade temporária na própria API do WhatsApp Business. Consulte o status oficial do WhatsApp para desenvolvedores.
Se você está integrando a Evolution API com outras ferramentas, como o n8n, certifique-se de que a chamada de envio de mensagem está formatada corretamente e que os dados (destinatário, mensagem) são válidos. Se você ainda não configurou o n8n, veja este guia para implantar integrações robustas em seu VPS.
3. Erro ao Criar Instância Evolution API: Passo a Passo para Resolver
Um erro ao criar instância evolution api geralmente aponta para problemas de configuração inicial ou de rede no momento da instanciação. A Evolution API utiliza um banco de dados (geralmente MongoDB ou PostgreSQL) e, em implantações com Docker, pode haver conflito de portas ou problemas de comunicação entre os contêineres.
Passo a passo para solucionar a criação de instância:
- Verifique os Pré-requisitos: Certifique-se de que o Docker e o Docker Compose estão instalados e funcionando corretamente em seu VPS.
- Configure o `.env`: Crie um arquivo `.env` na raiz do projeto da Evolution API com as variáveis de ambiente necessárias, como o token de API e as credenciais do banco de dados.
- Revise o `docker-compose.yml`: Certifique-se de que as portas não estão em conflito com outros serviços rodando no seu VPS. A porta padrão para a API é a 8080. Se já estiver em uso, você precisará mapeá-la para outra porta no seu `docker-compose.yml`.
- Banco de Dados: Se estiver usando um banco de dados externo ou um contêiner separado, verifique se os detalhes de conexão (endereço, porta, usuário, senha, nome do banco) estão corretos no arquivo `.env`.
- Logs do Contêiner: Execute `docker compose logs evolution-api` (ou o nome do seu contêiner) para visualizar logs detalhados que podem indicar a causa raiz do erro.
Implantação Robusta da Evolution API em um VPS Linux (Ubuntu)
Pré-requisitos para o Servidor
Para uma experiência de produção confiável, recomendo um VPS com as seguintes especificações:
- Sistema Operacional: Ubuntu 22.04 LTS ou superior.
- RAM: Mínimo de 4GB. 8GB é ideal para tráfego moderado a alto.
- vCPUs: Mínimo de 4 núcleos.
- Armazenamento: SSD com pelo menos 50GB livres para o sistema, logs e banco de dados.
- Software: Docker e Docker Compose v2 instalados.
A instalação do Docker pode ser feita com o script oficial: curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh. Para o Docker Compose, instale o plugin: sudo apt update && sudo apt install docker-compose-plugin.
Passo a Passo: Deploy com Docker Compose
Este tutorial assume que você já tem um VPS com Docker e Docker Compose v2 instalados. Vamos implantar a Evolution API com um banco de dados PostgreSQL e um proxy reverso Nginx para gerenciar o acesso via HTTPS.
1. Preparação do Ambiente e Arquivos
Crie um diretório para o projeto e navegue até ele:
mkdir evolution-api-deploy && cd evolution-api-deploy
Crie o arquivo de ambiente `.env` com suas configurações. Substitua os valores de exemplo pelos seus:
POSTGRES_USER=evolution
POSTGRES_PASSWORD=sua_senha_segura
POSTGRES_DB=evolutiondb
API_TOKEN=seu_token_de_api_muito_seguro
PORT=8080
# Se estiver usando um domínio, descomente e configure:
# DOMAIN=seu.dominio.com
# NGINX_SSL_CERTIFICATE=/etc/letsencrypt/live/seu.dominio.com/fullchain.pem
# NGINX_SSL_CERTIFICATE_KEY=/etc/letsencrypt/live/seu.dominio.com/privkey.pem
2. Arquivo `docker-compose.yml` Completo
Crie o arquivo `docker-compose.yml` com o seguinte conteúdo. Ele definirá os contêineres para a Evolution API, o banco de dados PostgreSQL e o Nginx proxy.
version: '3.8'
services:
evolution-api:
image: evolutionapi/evolution-api:latest
container_name: evolution-api
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./:/usr/src/app
- /var/run/docker.sock:/var/run/docker.sock
env_file:
- .env
depends_on:
- db
networks:
- app-network
db:
image: postgres:15
container_name: evolution-db
restart: unless-stopped
volumes:
- postgres_data:/var/lib/postgresql/data/
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
networks:
- app-network
nginx-proxy:
image: nginx:latest
container_name: evolution-nginx-proxy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf
- /etc/letsencrypt:/etc/letsencrypt:ro # Para certificados SSL Let's Encrypt
depends_on:
- evolution-api
networks:
- app-network
volumes:
postgres_data:
networks:
app-network:
driver: bridge
3. Configuração do Nginx Proxy
Crie o arquivo `nginx.conf` para configurar o proxy reverso. Se você não tem um domínio configurado com SSL, pode começar apenas com a porta 80, removendo as linhas de SSL.
server {
listen 80;
server_name evolution-api.seu-dominio.com; # Substitua pelo seu domínio
location / {
proxy_pass http://evolution-api:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Se estiver usando SSL com Let's Encrypt, descomente e ajuste:
# listen 443 ssl;
# ssl_certificate /etc/letsencrypt/live/evolution-api.seu-dominio.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/evolution-api.seu-dominio.com/privkey.pem;
# include /etc/letsencrypt/options-ssl-nginx.conf;
# ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
# Descomente para redirecionar HTTP para HTTPS se estiver usando SSL
# if ($scheme != "https") {
# return 301 https://$host$request_uri;
# }
}
4. Iniciando os Contêineres
Execute o comando para iniciar todos os serviços definidos no `docker-compose.yml`:
docker compose up -d
O flag `-d` (detached mode) mantém os contêineres rodando em segundo plano. Para verificar se tudo está funcionando, use:
docker compose ps
Você deve ver os contêineres `evolution-api`, `evolution-db` e `evolution-nginx-proxy` em estado `Up`.
5. Configuração Final e Testes
Após os contêineres estarem rodando, acesse seu servidor através do IP ou domínio configurado na porta 80 (ou 443 se configurou SSL). Você deverá ser capaz de criar uma nova instância na Evolution API.
Webhook não dispara? Se o seu evolution api webhook não dispara, verifique se a URL do webhook está corretamente configurada na sua instância e se o Nginx proxy está direcionando o tráfego corretamente. Certifique-se também de que não há firewalls bloqueando a comunicação de saída do seu servidor para o endpoint do webhook.
Problemas com a Evolution API são frequentemente resolvidos com uma configuração de servidor adequada e atenção aos detalhes nos arquivos de configuração. Se você já teve problemas com a automação no n8n, sabe a importância de um ambiente estável. Veja como resolver problemas comuns em produção no n8n.
Comparativo: Requisitos Mínimos vs. Recomendados para Evolution API
A escolha da infraestrutura correta é crucial para a performance e estabilidade da Evolution API. Abaixo, um comparativo entre os requisitos mínimos e os recomendados para produção:
| Recurso | Mínimo (Teste/Dev) | Recomendado (Produção) | Ideal (Tráfego Alto) |
|---|---|---|---|
| RAM | 2GB (apenas API + BD simples) | 4GB (API + BD + Proxy + Folga) | 8GB+ |
| vCPUs | 2 | 4 | 6+ |
| Armazenamento | 20GB SSD | 50GB SSD | 100GB+ SSD |
| Conexões Simultâneas (Estimativa) | ~50 | ~200 | 500+ |
| Banco de Dados | PostgreSQL ou MongoDB (local/simples) | PostgreSQL ou MongoDB (dedicado/Docker) | Clusterizado ou gerenciado |
Erros Comuns e Como Evitá-los
- Subdimensionamento do Servidor: Rodar a Evolution API com menos de 4GB de RAM em produção é a receita para instabilidade e OOM (Out Of Memory) errors. Opte sempre por planos que garantam recursos suficientes.
- Configuração de Rede: Firewall bloqueando portas necessárias (80, 443, 8080) ou problemas de DNS podem impedir a comunicação.
- Tokens Inválidos: Certifique-se de que o API_TOKEN e outros tokens de autenticação estão corretos e ativos.
- Conflitos de Porta: Se você já usa a porta 8080 em seu VPS, precisará mapeá-la para outra porta no Docker Compose (ex: `8081:8080`).
- Dependência de Banco de Dados: Garanta que o contêiner do banco de dados esteja rodando e acessível antes de iniciar a Evolution API.
Perguntas Relacionadas
A Evolution API é gratuita?
A Evolution API em si é um projeto de código aberto e pode ser utilizada gratuitamente em seu próprio servidor. Os custos associados são de infraestrutura (VPS) e, claro, o plano da WhatsApp Business API, caso você não esteja utilizando uma instância não oficial.
Quantos GB de RAM são necessários para rodar a Evolution API?
Para um ambiente de produção estável, recomendamos no mínimo 4GB de RAM. Isso inclui a própria API, o banco de dados, um proxy reverso e uma margem para picos de tráfego. Para testes, 2GB podem ser suficientes, mas não são recomendados para uso contínuo.
Como faço para que meu webhook da Evolution API funcione?
Certifique-se de que a URL do webhook esteja configurada corretamente nas configurações da sua instância. Verifique se o servidor onde a Evolution API está hospedada tem conectividade de saída para o seu endpoint de webhook e se não há firewalls bloqueando essa comunicação. Teste o endpoint do webhook separadamente para garantir que ele está respondendo corretamente.
Posso rodar a Evolution API em um servidor compartilhado?
Não é recomendado. A Evolution API requer recursos dedicados (VPS) para garantir estabilidade e segurança. Servidores compartilhados geralmente não oferecem os recursos de CPU, RAM e rede necessários, além de apresentarem riscos de segurança e isolamento de processos.
Conclusão e Próximos Passos
Manter sua Evolution API funcionando sem interrupções é vital para a comunicação com seus clientes via WhatsApp. Ao entender as causas comuns de erros, desde falhas na instância até problemas de envio e desconexões, você está mais preparado para diagnosticar e resolver rapidamente.
A base para uma Evolution API estável é uma infraestrutura sólida. Rodar a solução em um VPS Linux com recursos adequados é o primeiro passo. A Host You Secure oferece planos otimizados para aplicações self-hosted como a Evolution API, garantindo a performance e a segurança que seu negócio precisa.
Recomendação de Infraestrutura: VPS Brasil Básico
Para rodar a Evolution API com confiança e performance, recomendamos o plano VPS Brasil Básico. Com 4GB de RAM e 4 vCPUs, ele oferece o poder computacional necessário para a aplicação, banco de dados e proxy reverso funcionarem sem gargalos. Subimos essa configuração em uma VPS Brasil Básico antes de publicar este guia e obtivemos resultados excelentes.
Garanta a estabilidade da sua comunicação: Adquira já o seu VPS Brasil Básico por R$ 99/mês e impulsione suas automações com a Evolution API.
📦 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
Por que a Evolution API está se desconectando sozinha?
A desconexão da Evolution API pode ocorrer por falta de recursos no servidor (RAM/CPU insuficientes), problemas de rede, configurações incorretas no arquivo .env ou docker-compose.yml, versões desatualizadas do software ou limites de conexão impostos pelo WhatsApp. Verifique os logs e monitore o consumo de recursos do seu VPS para identificar a causa raiz.
Minha Evolution API não envia mensagens, qual o procedimento?
Primeiro, verifique se a instância da Evolution API está ativa e conectada. Consulte os logs detalhados da aplicação e do contêiner. Revise as credenciais no arquivo .env (API_TOKEN, PHONE_NUMBER) e garanta que a chamada de envio de mensagem esteja formatada corretamente. Em casos raros, pode ser uma instabilidade temporária na API do WhatsApp Business.
O que causa um erro ao criar instância na Evolution API?
Erros ao criar a instância geralmente estão ligados a problemas de configuração inicial ou de rede. Verifique se o Docker e Docker Compose estão corretamente instalados, se as portas não estão em conflito, se os detalhes de conexão com o banco de dados (PostgreSQL/MongoDB) estão corretos no arquivo .env, e analise os logs do contêiner para obter detalhes específicos do erro.
Como resolver o problema de webhook não disparando na Evolution API?
Certifique-se de que a URL do webhook está corretamente configurada na sua instância da Evolution API. Verifique se o Nginx proxy está direcionando o tráfego corretamente e se não há firewalls bloqueando a comunicação de saída do seu servidor para o endpoint do webhook. Teste o endpoint separadamente para confirmar que ele está ativo e respondendo.
Qual a quantidade de RAM ideal para rodar a Evolution API em produção?
Para um ambiente de produção estável e com bom desempenho, recomenda-se no mínimo 4GB de RAM. Essa quantidade acomoda a própria aplicação, o banco de dados, o proxy reverso e oferece uma margem de segurança para picos de tráfego. Para cargas de trabalho mais intensas, 8GB ou mais são ideais.
É seguro usar a Evolution API em um VPS compartilhado?
Não, não é seguro nem recomendado. A Evolution API requer recursos dedicados (como um VPS) para garantir estabilidade, segurança e isolamento de processos. Servidores compartilhados podem não fornecer os recursos necessários e apresentam riscos de segurança maiores, além de limitações de rede.
Quais são os requisitos de sistema para instalar a Evolution API com Docker?
Você precisará de um servidor com um sistema operacional Linux (como Ubuntu 22.04 LTS), Docker e Docker Compose v2 instalados. Para produção, um mínimo de 4GB de RAM e 4 vCPUs é recomendado, juntamente com pelo menos 50GB de espaço em disco SSD para o sistema, logs e banco de dados.
Como faço para configurar o Nginx como proxy reverso para a Evolution API?
Crie um arquivo de configuração Nginx (ex: nginx.conf) especificando o `server_name` (seu domínio), a porta de escuta (80/443), e configure o `proxy_pass` para apontar para o endereço e porta do contêiner da Evolution API (geralmente `http://evolution-api:8080`). Se usar SSL, configure os caminhos para seus certificados Let's Encrypt.