Evolution API desconectando do WhatsApp: como resolver
Se a Evolution API desconecta do WhatsApp com frequência, as causas mais comuns são: servidor fora do Brasil (latência alta derruba a sessão WebSocket), IP da VPS sem reputação limpa, ou a sessão não sendo persistida em banco — fazendo o QR code expirar a cada restart. Servidor no Brasil com IP fixo e PostgreSQL habilitado resolvem a maioria dos casos.
Diagnóstico: verificar o estado da conexão e os logs
Antes de qualquer mudança, veja o que a API está reportando. O endpoint de status e os logs do container revelam o motivo da desconexão:
# Ver estado da conexão da instância
curl -X GET "https://seu-servidor/instance/connectionState/sua-instancia" \
-H "apikey: sua-chave-api"
# Logs do container em tempo real
docker compose logs evolution -f --tail=100Causa 1: servidor fora do Brasil — latência derruba a sessão
A Evolution API mantém uma conexão WebSocket persistente com os servidores do WhatsApp. Servidores na Europa ou EUA têm latência de 150–250ms para os relays do WhatsApp, o que aumenta a probabilidade de timeout e desconexão. Servidores no Brasil (SP01) mantêm a conexão mais estável com latência < 30ms para os relays americanos.
Causa 2: sessão não persistida — reconexão exige QR code toda vez
Sem PostgreSQL configurado, a Evolution API armazena as sessões em memória ou em arquivos locais. Um restart do container apaga a sessão e o QR code precisa ser lido novamente. Para persistir a sessão entre restarts:
# Variáveis obrigatórias no docker-compose.yml para persistência
environment:
- DATABASE_ENABLED=true
- DATABASE_CONNECTION_URI=postgresql://evolution:senha@postgres:5432/evolution
- DATABASE_CONNECTION_CLIENT_NAME=evolution_api
# Redis para filas de mensagem (recomendado)
- REDIS_ENABLED=true
- REDIS_URI=redis://redis:6379
- REDIS_PREFIX_KEY=evolutionCausa 3: reconexão automática desabilitada
A Evolution API pode estar configurada para não tentar reconectar após uma queda. Verifique a variável de configuração de reconexão:
# Garantir reconexão automática habilitada
environment:
- CONFIG_SESSION_PHONE_CLIENT=Evolution API
- CONFIG_SESSION_PHONE_NAME=Chrome
# Após alterar, recrie o container
docker compose up -d evolutionCausa 4: número banido ou sessão invalidada pelo WhatsApp
Se nos logs aparecer Stream errored (unauthorized) ou a API retornar status banned, o número foi banido pelo WhatsApp. Isso acontece quando o número é usado em volumes muito altos de mensagens não solicitadas ou quando o WhatsApp detecta uso de cliente não oficial.
Como monitorar a conexão continuamente
Para detectar desconexões rapidamente e acionar alertas, use o webhook de CONNECTION_UPDATE ou um script de health check:
#!/bin/bash
# /opt/check-evolution.sh — verificar se a instância está conectada
INSTANCE="sua-instancia"
API_KEY="sua-chave-api"
URL="https://seu-servidor/instance/connectionState/$INSTANCE"
STATE=$(curl -s -H "apikey: $API_KEY" "$URL" | grep -o '"state":"[^"]*"' | cut -d'"' -f4)
if [ "$STATE" != "open" ]; then
echo "ALERTA: instância $INSTANCE desconectada (state=$STATE)"
# Aqui: enviar notificação via e-mail, Telegram, etc.
fi$ runstack deploy --plan starter
Não quer configurar manualmente?
Não quer configurar manualmente? Implante o Evolution API em menos de 3 minutos com a Runstack. Infraestrutura da OPEN DATACENTER, com servidores no Brasil.