Bot parou de responder. Você abre Kontato, badge do WhatsApp vermelho. Calma — geralmente resolve em 1 passo.
Primeiro: confere se é desconexão real
Desde v0.26.6, badge tem 3 estados pra evitar falso positivo:
- 🟢 Verde = WORKING confirmado (tudo OK)
- 🔴 Vermelho = STOPPED, FAILED, SCAN_QR_CODE, NOT_FOUND (desconexão real)
- ⚪ Cinza = incerteza (latência, timeout) — não é desconexão
Se badge está cinza, sistema está em retry exponencial (3s → 6s → 12s). Espera ~20s e refresca. Quase sempre volta verde sozinho.
Se badge está vermelho, é desconexão real → segue diagnóstico.
Diagnóstico (3 passos)
Passo 1 — Celular do WhatsApp tá ligado?
A conexão usa WhatsApp Web por trás. Se seu celular está:
- ❌ Desligado
- ❌ Sem bateria
- ❌ Em modo avião
- ❌ Sem internet (Wi-Fi ou 4G)
Web desconecta após ~15min de inatividade.
Fix: verifica celular, conecta na internet, abre WhatsApp normal pra "acordar".
Passo 2 — Restart da conexão WhatsApp
Se celular tá OK mas badge vermelho:
Vai em Atendimento → Conectar WhatsApp.
Click "Reiniciar conexão" (ou similar).
Sistema recria a conexão WhatsApp — pode pedir QR Code novamente.
Se aparecer QR, segue passo 3.
Passo 3 — Reconectar via QR ou Pairing Code
Via QR Code
- Tela mostra QR grande
- Abre WhatsApp no celular → Aparelhos conectados → Conectar um aparelho → escaneia QR
- Aguarda ~5s — badge vira verde
Via Pairing Code (alternativa, sem precisar QR)
- Click "Usar código de 8 dígitos" na tela de conectar
- Digita seu telefone com DDI (ex: 5511999999999)
- Sistema chama a API do WhatsApp → retorna código de 8 dígitos (ex: A1B2 C3D4)
- No WhatsApp celular: Aparelhos conectados → Vincular pelo número → digita o código
- Aguarda ~10s — badge vira verde
Causas comuns de desconexão
| Causa | Solução |
|---|---|
| Bateria descarregou no celular | Carrega + reabre WhatsApp |
| Celular trocou de rede (Wi-Fi → 4G) | WhatsApp normal reconecta sozinho — mas a conexão do bot pode precisar de restart |
| Celular ficou no modo avião | Tira modo avião, abre WhatsApp |
| WhatsApp foi desinstalado/reinstalado | Reconecta via QR (sessão antiga é descartada) |
| WhatsApp Business virou pessoal (ou vice-versa) | Reconecta — mesma conta, sessão nova |
| Servidor reiniciou (manutenção TMB) | Aguarda ~5min, reconecta automaticamente |
| Mais de 4 dispositivos vinculados | WhatsApp limita a 4 — desvincula um aparelho antigo no celular |
| Você apagou conta WhatsApp | Não tem como recuperar — cria nova conta + reconecta |
Bot não responde mas badge tá verde
Caso raro mas existe. Se badge está verde mas bot não responde mensagem:
Manda mensagem pra você mesmo (do seu celular pessoal pro número do negócio).
Espera 10s. Bot deveria responder.
Se NÃO respondeu:
- Verifica em /configuracoes/ia se persona está ativa
- Verifica se KB tem itens
- Verifica em /conversas se sua mensagem chegou no app (sintoma de "chegou no app, IA não rodou" = problema de OpenRouter)
- Verifica se conversa não está pausada manualmente ou automaticamente
Sessão pré-v0.26.6 — não emite session.status
Se sua sessão foi criada antes de 06/maio/2026 (v0.26.6), webhook session.status não chega na Kontato. Badge cai no fallback de polling.
Sintoma: badge demora ~30s pra atualizar quando você reconecta (vs ~3s nas sessões novas).
Fix: sua conta de admin TMB executa o endpoint POST /api/admin/reconfig-waha-sessions (script one-shot). Após isso, sessão emite eventos em real-time.
Se você é dono e percebeu isso, reporta pro suporte — TMB roda o script.