Evolution API: Solucionando Problemas de Conexão e Webhooks

O que Causa Problemas na Evolution API em um VPS?

Problemas na Evolution API, como evolution api desconectando sozinha, evolution api não envia mensagem ou evolution api webhook não dispara, geralmente são causados por uma combinação de fatores, incluindo recursos insuficientes do servidor, configuração inadequada do ambiente, instabilidade de rede ou falhas na própria aplicação. A Evolution API, sendo uma ferramenta self-hosted, depende diretamente da qualidade e configuração do seu ambiente de hospedagem. Para garantir um funcionamento contínuo, é crucial ter um VPS bem dimensionado e configurado corretamente.

Veja a infraestrutura: VPS para n8n + Evolution API para colocar este projeto no ar.

Na minha experiência, muitos dos problemas de instabilidade e desempenho da Evolution API surgem de ambientes mal configurados ou com recursos limitados. Um VPS com pouca RAM ou CPU pode levar a falhas inesperadas, desconexões e atrasos no processamento de mensagens. Por exemplo, vi casos em que a Evolution API travava completamente em VPSs com menos de 2GB de RAM, especialmente sob carga média. Para um ambiente de produção robusto, a Evolution API (com seus serviços e um banco de dados como o PostgreSQL) requer pelo menos 4GB de RAM e 2 vCPUs.

Diagnóstico Inicial para Falhas na Evolution API

Antes de mergulhar em soluções complexas, um diagnóstico inicial preciso pode economizar muito tempo. Entender a natureza do problema é o primeiro passo para resolvê-lo. Isso inclui verificar os logs, o status dos serviços e a conectividade básica.

Verificando Logs da Aplicação

Os logs são a principal fonte de informação sobre o que está acontecendo internamente na Evolution API. Se sua instância estiver rodando via Docker Compose, você pode acessar os logs de forma simples. Procure por mensagens de erro, warnings ou qualquer indicação de falha. Um erro comum é a falha na conexão com o WhatsApp ou problemas de autenticação.

docker compose logs -f evolution-api

Este comando irá exibir os logs em tempo real do serviço evolution-api. Preste atenção a mensagens como Error: Failed to connect to WhatsApp, Auth failed, ou Connection closed. Essas mensagens podem indicar problemas com a internet do VPS, QR Code expirado ou uma sessão corrompida.

Checando o Status dos Containers Docker

É fundamental garantir que todos os serviços Docker que compõem a sua instância da Evolution API estejam em execução. Se algum container estiver parado ou reiniciando em loop, a aplicação não funcionará corretamente. Utilize o comando abaixo para verificar o status de todos os containers no seu VPS:

docker compose ps

Verifique se todos os serviços listados estão com o status Up. Se algum estiver como Exited ou Restarting, investigue os logs desse container específico (usando docker compose logs -f <nome_do_serviço>) para entender a causa da falha. Por exemplo, se o serviço do banco de dados (geralmente PostgreSQL ou Redis) estiver falhando, a Evolution API não conseguirá inicializar.

Resolvendo Problemas de Conexão e Desconexões Frequentes

A evolution api desconectando sozinha é um dos problemas mais reportados e frustrantes. Geralmente, está ligada à instabilidade da rede, recursos do servidor ou falhas na sessão do WhatsApp.

Otimização de Recursos do VPS

Um VPS subdimensionado é a causa raiz de muitas desconexões. A Evolution API, especialmente com múltiplas instâncias ou alto volume de mensagens, pode consumir bastante CPU e RAM. Se o sistema operacional estiver sem memória, ele pode encerrar processos da Evolution API para liberar recursos, causando desconexões. Certifique-se de que seu VPS possui RAM e CPU adequadas. Para produção, recomendo no mínimo 4GB de RAM e 2 vCPUs, que são os requisitos mínimos para manter a aplicação e seus serviços auxiliares estáveis. Em casos de alto volume de tráfego, um plano com 8GB de RAM e 4 vCPUs pode ser mais apropriado. Se você já tem um VPS e está enfrentando desconexões, verifique o uso de memória e CPU com ferramentas como htop ou free -h. Se estiverem consistentemente altos, é um sinal claro de que você precisa de mais recursos.

Gerenciamento de Sessão e QR Code

A sessão do WhatsApp pode se tornar inválida por diversos motivos: o telefone se desconectou da internet, o QR Code expirou antes de ser escaneado, ou houve uma tentativa de login em outro dispositivo. Quando a sessão se torna inválida, a Evolution API desconecta. Para resolver, você precisará recarregar o QR Code ou reiniciar a sessão. Utilize os endpoints da própria API para gerar um novo QR Code e escanear novamente. Em alguns casos, pode ser necessário excluir o diretório de sessão no servidor (geralmente mapeado via volume Docker) para forçar uma nova inicialização limpa. Isso é um erro comum que já ajudei clientes a resolverem, onde a solução era simplesmente limpar a sessão e reconectar o WhatsApp. Para mais dicas sobre este tipo de problema, confira nosso artigo sobre Evolution API: Resolva Erros e Otimize a Conexão.

Diagnóstico e Solução para Mensagens Não Enviadas

Quando a evolution api não envia mensagem, o problema pode estar na conectividade do servidor, na configuração da API ou em limitações da plataforma WhatsApp.

Verificação de Conectividade de Rede

A Evolution API precisa de acesso constante à internet para enviar e receber mensagens. Verifique a conectividade do seu VPS. Um teste simples é tentar fazer um ping para um servidor externo ou usar curl para acessar uma URL. Se o VPS estiver com problemas de rede, as mensagens não serão enviadas. Verifique também as regras de firewall (UFW ou do provedor de cloud) para garantir que não estão bloqueando o tráfego de saída.

ping google.com
curl -I https://api.whatsapp.com/ 

Se o ping ou curl falharem, o problema é de rede do VPS. Se funcionarem, o problema é mais específico da Evolution API.

Configuração Correta da API e Endpoints

Certifique-se de que os endpoints da Evolution API estão sendo chamados corretamente, com os parâmetros e token de autenticação certos. Um erro comum é usar um token incorreto ou tentar enviar mensagens para um número de telefone com formato inválido. Consulte a documentação da Evolution API para verificar os formatos esperados. Além disso, se você estiver utilizando um proxy reverso (como Nginx ou Caddy), verifique se ele está configurado para encaminhar as requisições corretamente para o container da Evolution API. Uma configuração de proxy incorreta pode levar a erros 502 Bad Gateway ou 404 Not Found, impedindo o envio de mensagens. Se precisar de ajuda com a configuração do proxy reverso, temos um guia completo de Evolution API: Diagnóstico Avançado e Otimização em VPS que pode auxiliar.

Resolução de Problemas com Webhooks e Instâncias

A falha de evolution api webhook não dispara ou erro ao criar instância evolution api pode comprometer seriamente a automação e o gerenciamento da aplicação.

Debugging de Webhooks

Webhooks são essenciais para receber notificações de eventos do WhatsApp. Se eles não estão disparando, o problema pode estar em três lugares: a Evolution API não está enviando, o servidor de destino não está recebendo, ou há um problema de rede/firewall no caminho. Primeiramente, verifique os logs da Evolution API para ver se há erros relacionados ao envio do webhook. Muitos frameworks de automação como o n8n possuem um webhook tester que permite verificar se as requisições estão chegando ao seu destino. Garanta que a URL do webhook configurada na Evolution API esteja correta e acessível publicamente pela internet (e não apenas internamente na sua rede). Se seu servidor de destino está por trás de um firewall, as portas necessárias (geralmente 80 ou 443) devem estar abertas para receber as requisições.

Erros ao Criar ou Gerenciar Instâncias

Um erro ao criar instância evolution api pode ser causado por diversos fatores, incluindo permissões de arquivo, problemas no banco de dados ou configurações inválidas. Verifique os logs do Docker Compose durante a inicialização para identificar a mensagem de erro específica. Se o problema for relacionado a permissões, garanta que o usuário que está executando os comandos Docker tem acesso de escrita aos volumes mapeados. Se o banco de dados não estiver acessível ou configurado corretamente, a Evolution API não conseguirá inicializar novas instâncias. Confirme as variáveis de ambiente relacionadas ao banco de dados (DATABASE_URL, REDIS_URL, etc.) no seu arquivo .env. Um erro comum é usar caracteres especiais em senhas que não são escapados corretamente nas variáveis de ambiente, causando falha na conexão com o banco de dados.

Passo a Passo: Deploy Robusto da Evolution API com Docker Compose

Para mitigar a maioria dos problemas de estabilidade, um deploy bem estruturado em um VPS com Docker Compose é fundamental. Este tutorial aborda a instalação em um Ubuntu Server 22.04 LTS.

Preparação do Ambiente no VPS

Primeiro, conecte-se ao seu VPS via SSH. Atualize o sistema e instale o Docker e o Docker Compose. Recomendo um VPS com no mínimo 4GB de RAM e 2 vCPUs para produção.

sudo apt update && sudo apt upgrade -y
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
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
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y
sudo usermod -aG docker $USER
newgrp docker

Após instalar o Docker, crie um diretório para a Evolution API e navegue até ele:

mkdir evolution-api && cd evolution-api

Configuração do Docker Compose

Crie um arquivo docker-compose.yml e um arquivo .env com as configurações essenciais. Este exemplo inclui a Evolution API, um banco de dados PostgreSQL e o Redis para gerenciamento de filas e cache.

docker-compose.yml:

version: '3.8'

services:
  evolution-api:
    image: evolutionapi/evolution-api:latest
    container_name: evolution-api
    environment:
      EVO_TOKEN: ${EVO_TOKEN}
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
      WEBHOOK_URL: ${WEBHOOK_URL}
      PORT: 8080
      GLOBAL_TIMEOUT: 60000
      ENABLE_OFFICIAL_BETA: "true"
      ALLOW_AUTO_UPDATE: "false"
      API_KEY: ${API_KEY}
    ports:
      - "8080:8080"
    volumes:
      - ./evolution-data:/app/data
    depends_on:
      - db
      - redis
    restart: always

  db:
    image: postgres:15-alpine
    container_name: postgres-db
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: always

  redis:
    image: redis:7-alpine
    container_name: redis-cache
    volumes:
      - ./redis-data:/data
    restart: always

networks:
  default:
    driver: bridge

.env:

EVO_TOKEN=seu_token_aqui_para_autenticacao
POSTGRES_DB=evolutiondb
POSTGRES_USER=evolutionuser
POSTGRES_PASSWORD=sua_senha_segura_para_postgres
WEBHOOK_URL=https://seu_servidor_webhook.com/receber-eventos
API_KEY=sua_chave_api_para_seguranca_opcional

Substitua seu_token_aqui_para_autenticacao, sua_senha_segura_para_postgres, https://seu_servidor_webhook.com/receber-eventos e sua_chave_api_para_seguranca_opcional pelos seus valores reais. A EVO_TOKEN é um token que você pode definir para proteger o acesso à sua Evolution API, enquanto a API_KEY é uma chave de segurança adicional que algumas versões da Evolution API utilizam para autenticação em determinados endpoints.

Iniciando a Evolution API e Verificando o Status

Com os arquivos docker-compose.yml e .env configurados, inicie os serviços:

docker compose up -d

Verifique o status:

docker compose ps

Todos os serviços devem estar Up. Acesse a interface da Evolution API em http://seu_ip_do_vps:8080 para escanear o QR Code e iniciar a sessão. Em caso de problemas, utilize docker compose logs -f <nome_do_serviço> para depurar.

Erros Comuns e Como Evitá-los

Ao configurar e manter a Evolution API, alguns erros são recorrentes e podem ser evitados com boas práticas.

Recursos Insuficientes

Um dos erros mais comuns é subestimar os requisitos de hardware. Tentar rodar a Evolution API (com PostgreSQL e Redis) em um VPS com 2GB de RAM é uma receita para instabilidade e desconexões. O sistema operacional já consome uma parte considerável da RAM, deixando pouco para os containers. Sempre dimensione seu VPS com folga. Para o ambiente mínimo de produção que descrevemos, 4GB de RAM é o ponto de partida ideal. Se você planeja muitas instâncias ou alto volume de mensagens, considere 8GB de RAM.

Configuração Incorreta de Variáveis de Ambiente

Pequenos erros nas variáveis de ambiente podem causar grandes problemas. Senhas com caracteres especiais sem aspas, URLs de banco de dados ou Redis digitadas incorretamente, ou tokens ausentes são fontes comuns de falha. Sempre revise seu arquivo .env e os logs de inicialização para identificar variáveis ausentes ou inválidas.

Problemas de Rede e Firewall

Verifique se as portas necessárias estão abertas no firewall do VPS (porta 8080 para acesso à API, e se estiver usando um proxy reverso, portas 80 e 443). Muitos provedores de VPS também possuem um firewall de rede externo que precisa ser configurado. Lembre-se que o WhatsApp utiliza protocolos específicos e qualquer bloqueio de rede pode impedir a conexão e o envio de mensagens. Certifique-se de que o VPS tem conectividade de internet estável e sem restrições de saída.

Análise de Causas de Problemas na Evolution API

Perguntas Relacionadas

Como evitar a Evolution API desconectando sozinha?

Para evitar desconexões frequentes, garanta que seu VPS tenha recursos de hardware adequados (mínimo 4GB de RAM e 2 vCPUs), mantenha sua sessão do WhatsApp ativa no telefone, e configure um proxy reverso robusto. Reinicie a sessão da API se o QR Code expirar ou se o telefone perder a conexão com a internet. Verifique os logs regularmente para identificar padrões de falha.

Qual a melhor forma de debuggar mensagens que não são enviadas pela Evolution API?

Comece verificando os logs do container evolution-api para mensagens de erro. Em seguida, teste a conectividade de rede do seu VPS e confirme se o token de acesso e o formato do número de telefone estão corretos na sua requisição. Verifique também se o WhatsApp do telefone está conectado e se a sessão da API está ativa e válida.

É necessário um proxy reverso para a Evolution API em produção?

Sim, é altamente recomendável usar um proxy reverso como Nginx ou Caddy em produção. Ele oferece segurança (SSL/HTTPS), balanceamento de carga, cache e facilidade de gerenciamento de múltiplos domínios. Embora a API funcione sem, um proxy reverso melhora a estabilidade, segurança e performance do seu deploy, expondo a Evolution API de forma profissional.

Como lidar com "erro ao criar instância evolution api"?

Esse erro geralmente aponta para problemas na configuração do banco de dados (PostgreSQL/Redis), permissões de volume Docker, ou variáveis de ambiente incorretas. Revise o arquivo .env, verifique se os containers de banco de dados estão funcionando e se os volumes têm permissão de escrita. Consulte os logs do container da Evolution API durante a inicialização para a mensagem de erro exata.

Conclusão: Mantenha sua Evolution API Estável com um VPS Robustos

Manter a Evolution API funcionando de forma estável e confiável exige atenção à infraestrutura, configuração e monitoramento. Resolver problemas como desconexões, mensagens não enviadas e webhooks falhos passa por um diagnóstico cuidadoso e a implementação de soluções robustas. Um ambiente de produção bem dimensionado, com recursos adequados e uma configuração otimizada, é a chave para o sucesso.

Para garantir que sua Evolution API funcione sem interrupções, você precisa de um servidor confiável. O VPS Brasil Básico da Host You Secure é ideal para rodar a Evolution API com Docker Compose, oferecendo 4GB de RAM e 4 vCPUs, o que é mais do que suficiente para um deploy estável em produção. Rodamos esse exato setup em uma VPS Brasil Básico para muitos de nossos clientes, garantindo performance e confiabilidade.

Invista na estabilidade das suas automações hoje mesmo. Adquira seu VPS Brasil Básico por apenas R$ 99/mês e diga adeus aos problemas de instabilidade da Evolution API!