WhatsApp desconectando sozinho: checklist de debug com 12 causas e soluções

"WhatsApp desconecta sozinho", "QR code não escaneia", "instância caiu de novo" — três das dúvidas mais comuns de quem opera WhatsApp em produção. Em 9 de cada 10 casos, a causa é uma das 12 listadas abaixo, e cada uma tem solução determinística.

Use este artigo como checklist: percorra na ordem, valide o sintoma, aplique a correção. Inclui comandos de diagnóstico e métricas que a ZAP API expõe para acelerar a investigação.

1. Sessão multidevice expirada (>14 dias)

Sintoma: instância para de receber/enviar do nada, dashboard mostra "desconectada", QR code aparece pedindo nova leitura.

Causa: o WhatsApp expira sessões multidevice se o telefone vinculado ficou 14 dias sem internet, ou se você nunca abriu o app no celular nesse período.

Fix: abra o WhatsApp no celular vinculado, deixe-o online por uns segundos. Se já passou de 14 dias, a sessão sumiu — pareie de novo.

Prevenção: mantenha o celular vinculado ligado e online. Se for chip dedicado para a operação, deixe num lugar com Wi-Fi estável.

2. Conflito de sessão: outro dispositivo escaneou o QR

Sintoma: sessão cai a cada 1–5 minutos. Logs do gateway mostram "logout" repetido.

Causa: alguém escaneou o QR code do mesmo número em outro WhatsApp Web/Desktop. O WhatsApp permite até 4 sessões simultâneas — ao ultrapassar, a mais antiga é desconectada.

Fix: no celular vinculado, vá em Configurações → Aparelhos conectados e desconecte tudo. Em seguida, reconecte só a instância da API.

3. Versão antiga do WhatsApp no celular

Sintoma: tipos de mensagem novos (lista interativa, botão, reação) falham silenciosamente. Outros tipos funcionam.

Causa: o WhatsApp atualiza protocolos a cada ~3 meses. Versão de 2 anos atrás não fala "dialeto" novo.

Fix: atualize o app no celular vinculado para a versão mais recente. Após atualizar, espere 5 minutos antes de testar (o protocolo renegocia).

4. Banimento parcial (warning silencioso)

Sintoma: mensagens são marcadas como enviadas (✓) mas nunca entregues (✓✓). Acontece só com alguns destinatários.

Causa: o número está com restrição de envio para contas que não têm você na lista de contatos. É o "shadow ban" — passo intermediário antes de ban completo.

Fix: não há reverter rápido. Pare imediatamente os envios em massa, espere 48–72h, retome com cadência muito reduzida (ver artigo "Anti-ban WhatsApp"). Reduza taxa de denúncia: revise copy.

5. Bateria/economia agressiva no celular vinculado

Sintoma: instância funciona normal de dia, cai à noite ou nos fins de semana.

Causa: Xiaomi, Huawei, Samsung One UI matam o WhatsApp em background quando a tela está apagada por algumas horas, mesmo com bateria sobrando.

Fix:

• Vá em Configurações → Bateria e marque o WhatsApp como "sem restrição".
• Desative "otimização de bateria" para o app.
• Em Xiaomi: Configurações → Apps → WhatsApp → Auto-início (ative) e Economia de bateria (desative).
• Plugue o celular numa tomada permanente — bateria 100% também ajuda contra throttling térmico.

6. Rede instável (NAT timeout)

Sintoma: desconexões a cada 30–90 segundos, sem padrão claro.

Causa: seu firewall/router tem timeout curto de NAT em conexão TCP idle. Websocket do WhatsApp envia keepalive, mas se intervalo > timeout, conexão é dropada.

Fix:

• Em router doméstico, geralmente o timeout é configurável em Avançado → NAT/firewall.
• No backend (se você roda via container), ajuste keepalive do TCP socket: net.ipv4.tcp_keepalive_time = 60.
• Se for celular vinculado em Wi-Fi público (cafeteria, coworking), troque para 4G — Wi-Fi público corta tudo.

7. Token de API expirado ou rotacionado

Sintoma: chamadas de envio retornam 401 Unauthorized.

Fix:

• Acesse /dashboard/api-tokens e confirme se o token está ativo.
• Se foi rotacionado, gere um novo e atualize ZAP_TOKEN em todos os .env (backend, n8n, scripts).
• Convenção: nomeie tokens por ambiente (prod-2026, staging) para não confundir.

8. Webhook URL inalcançável (timeout 5s)

Sintoma: mensagens são enviadas, mas você não recebe inbound. No painel /dashboard/webhooks, todas as entregas estão em "failed" com ECONNREFUSED ou ETIMEDOUT.

Fix:

• Teste a URL de fora da sua rede: curl -X POST -d '{}' https://seu-app.com/webhook. Tem que retornar < 5s.
• Verifique se o domínio resolve via DNS público.
• Se for ngrok/localtunnel em dev, confirme que a sessão não expirou.
• Em produção, garanta que o endpoint responde 2xx em < 5s — se demorar mais, enfileire e responda imediato (padrão "ack first" — ver artigo Webhook).

9. Rate limit do gateway estourado

Sintoma: envios começam a falhar com 429 Too Many Requests após picos.

Causa: rate limit padrão da ZAP API é 60 requests/minuto por instância. Acima disso, retorna 429 com header Retry-After.

Fix:

• Implemente fila com throttle (ver artigo "Anti-ban").
• Para volume alto, divida em múltiplas instâncias.
• Respeite o Retry-After em vez de retentar imediatamente.

10. QR code expira em 60 segundos

Sintoma: "esqueci de scanear, fui buscar o celular, voltei e não funciona".

Causa: o QR code do WhatsApp tem validade de 60s. Após isso, o gateway gera um novo automaticamente.

Fix: deixe o celular pronto antes de clicar em Conectar. Em /dashboard/instances/:id/qrcode, o frontend faz polling automático e troca o QR antes de expirar.

11. Skew de relógio do servidor

Sintoma: erros flaky em assinatura HMAC, em login, em validação de webhook.

Causa: relógio do servidor está > 30 segundos defasado. Acontece em VPS sem NTP configurado, ou em containers que ficam dias rodando.

Fix:

// Verifique o desvio
date -u
# Compare com tempo correto: https://time.is

# Force sync (Linux)
sudo timedatectl set-ntp true
sudo systemctl restart systemd-timesyncd

12. Spam pattern detection

Sintoma: instância que ia bem fica subitamente com taxa de entrega < 50%, sem desconectar.

Causa: o WhatsApp detectou padrão suspeito (mesmo texto para 1.000 contatos, links encurtados, palavras de phishing). Não bane, mas reduz seu alcance.

Fix: revise as últimas 100 mensagens enviadas. Quebre padrões: introduza spintax, varie horário, reduza volume por 48h. Geralmente recupera sozinho em 3–7 dias.

Como diagnosticar via Session Quality

A ZAP API expõe um health score por instância em GET /v1/instances/:id/health:

{
  "instanceId": "inst_abc",
  "state": "degraded",
  "qualityScore": 72,
  "metrics": {
    "disconnectsLast24h": 4,
    "avgLatencyMs": 1840,
    "errorRate1h": 0.08,
    "lastInboundAt": "2026-04-30T11:23:00Z",
    "lastOutboundAt": "2026-04-30T11:24:11Z"
  },
  "recommendations": [
    "Multidevice expirou? Confirme no celular.",
    "Latência alta — verifique rede do gateway."
  ]
}

Score < 70 = atenção. < 50 = ação imediata.

FAQ

• Quanto tempo leva para reconectar após pareamento?
  Geralmente 5–15 segundos. Se passar de 1 minuto, há problema de rede entre o gateway e o WhatsApp.
• Posso ter mais de uma sessão da mesma instância?
  Não. Uma instância = uma sessão. Para volumes maiores, crie múltiplas instâncias com chips diferentes.
• O que é "lastDisconnectStreak"?
  Contador de desconexões consecutivas sem reconectar. Se chega a 10, a ZAP API dispara alerta automático para o admin.
• Posso forçar QR code novo?
  Sim — POST /v1/instances/:id/disconnect e em seguida POST /v1/instances/:id/connect.
• WhatsApp Business multidispositivo é diferente do WhatsApp normal?
  Não para fins de API — ambos usam o mesmo protocolo multidevice e têm os mesmos sintomas.

Criar conta com Health Score por instância — trial 7 dias.