Pular para o conteúdo
EntrarCriar minha VPS

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:

bash
# 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=100

Causa 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:

yaml
# 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=evolution

Causa 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:

yaml
# 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 evolution

Causa 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:

bash
#!/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

Não quer configurar manualmente?

Implante o Evolution API em menos de 5 minutos com a Runstack. Infraestrutura da OPEN Datacenter, com servidores em São Paulo.

Criar minha VPSVer apps prontos

Perguntas frequentes

Uma instância estável em servidor brasileiro com PostgreSQL habilitado pode ficar conectada por semanas sem desconectar. Desconexões frequentes (várias por dia) indicam problema de configuração, latência ou que o número está sendo monitorado pelo WhatsApp.

Com DATABASE_ENABLED=true e PostgreSQL configurado, a reconexão é automática após restart do container. Se a sessão foi invalidada pelo WhatsApp (ban ou expiração), o QR code precisará ser escaneado novamente via GET /instance/connect/{instanceName}.

O WhatsApp não bane IPs diretamente, bane números de telefone. Números usados em volume alto de mensagens não solicitadas ou detectados como bot têm maior risco de ban independente do IP. Um IP limpo (não em listas de spam) ajuda, mas o comportamento do número é o principal fator.

Sim, a Evolution API v2 implementa reconexão automática quando a sessão está persistida em banco. Após uma desconexão de rede temporária, ela tenta reconectar sem intervenção manual. Sessões invalidadas pelo WhatsApp (por inatividade ou ban) exigem novo QR code.

Para uma instância única: 1 vCPU e 1 GB RAM são suficientes (Runstack Micro, R$ 59/mês). Para múltiplas instâncias com PostgreSQL e Redis: 2 vCPU e 4 GB RAM (Runstack Pro, R$ 144/mês) suportam de 5 a 10 instâncias simultâneas confortavelmente.

Continue lendo