Anti-ban e rotação de números

Pra evitar que números WhatsApp do cliente sejam bloqueados quando o volume sobe, o BeeZap roteia automaticamente os envios entre os chips conectados, respeita janelas de descanso após falhas e enforça uma curva de aquecimento (warmup) em chips novos.

Depende da engine ativa

WAHA Core aceita só 1 sessão por instância. Nesse modo, o "router" sempre escolhe a única sessão. Com WAHA Plus, o BeeZap consegue cadastrar N chips por cliente e a lógica de rotação passa a ter efeito real.

Estratégias de seleção

Quando você chama POST /v1/messages sem informar sessionId ou sessionName, o BeeZap escolhe a melhor sessão usando uma das estratégias abaixo. O default do cliente é configurável por aqui (em breve via UI; hoje pelo admin do hub).

Estratégia	Lógica	Quando usar
STICKY	Se já trocou mensagem com aquele `chatId` nos últimos 14 dias usando uma sessão, mantém a mesma. Caso contrário, cai em `LEAST_USED`.	Default. Reduz risco de spam-flag pelo WhatsApp (recipient ver "diferentes números" mandando msg vira sinal vermelho).
LEAST_USED	Pega a sessão com menor contador de mensagens enviadas hoje.	Distribuição uniforme. Bom pra disparos de massa onde o destinatário muda toda vez.
ROUND_ROBIN	Alterna sequencialmente: pega a sessão cuja última mensagem é a mais antiga.	Quando você quer rotação determinística independente do volume diário.

Pra forçar uma estratégia diferente em uma chamada específica, mande poolStrategy no body:

json

{
  "chatId": "5511999999999@c.us",
  "text": "Promo do dia",
  "poolStrategy": "LEAST_USED"
}

Warmup (aquecimento de chip novo)

WhatsApp marca chips muito novos que disparam volume alto desde o dia 1. Pra mitigar, o BeeZap aplica um ramp automático da cota diária baseado em quantos dias a sessão está conectada:

Dias desde a 1ª conexão	Cota diária
0–6	20
7–13	40
14–20	60
21–27	80
28+	limite cheio (default 100)

O ramp só limita pra baixo: se a sessão tem dailyLimit = 60 definido pelo admin, mesmo após 28 dias o teto continua 60.

warmupStartAt é setado automaticamente na primeira vez que a sessão fica CONNECTED (via webhook da engine). Se você precisar resetar (ex: chip trocou de dono), peça ao admin do hub.

Cooldown automático

Se uma sessão retorna 3 erros consecutivos do tipo 5xx no envio (problema da engine WhatsApp, não validação), o router coloca ela em cooldownUntil = agora + 30min e desvia o tráfego pras outras sessões. Após o cooldown, o contador é zerado e ela volta ao pool.

4xx (número inexistente, body inválido) não conta — é problema do caller, não da sessão.
Sucesso (2xx) zera o contador imediatamente.
Webhook reportando BANNED tira a sessão do pool definitivamente (status muda; não volta sozinho).

Cota diária reseta meia-noite BRT

Os contadores são calculados sobre MessageLog com createdAt >= 00:00 BRT (America/Sao_Paulo, UTC-3). Reseta sozinho à meia-noite do horário de Brasília — não tem cron, é uma janela deslizante baseada no timestamp.

Forçar uma sessão específica

Bypassa o router enviando sessionId ou sessionName no body. Quando você força, o BeeZap ainda checa cooldown e cota — se a sessão estiver indisponível, devolve 503 ao invés de cair pra outra.

json

{
  "chatId": "5511999999999@c.us",
  "text": "Resposta operacional",
  "sessionName": "Suporte"
}

Use isso pra mensagens transacionais críticas (ex: "Suporte" sempre responde do número de suporte) — pra marketing, deixa o router decidir.

Boas práticas WhatsApp

Aquecer chips manualmente: nas 1ªs semanas, troque mensagens reais com humanos pelo número antes de mandar disparos automáticos. WhatsApp avalia "comportamento humano".
Variar o texto: enviar exatamente a mesma string pra 100 contatos é red flag. Use templates com placeholders ou pequenas variações.
Não mandar pra contatos que não te conhecem: a maioria dos bans vem de bulk pra números que nunca te enviaram nada. Trabalhe com opt-in.
Respeitar opt-out: se alguém pedir pra parar (palavras: "sair", "pare", "cancelar"), pare. O BeeZap não tem opt-out global ainda — implemente no seu lado.
Janela de horário: evitar disparar antes das 8h ou depois das 20h. Recipient marca como spam mais facilmente fora do horário comercial.
Múltiplos chips: 5 chips com 100 msgs/dia cada vai ter saúde melhor que 1 chip com 500/dia. Use STICKY pra cada destinatário sempre falar com o mesmo.

Monitoramento

Em /app/sessoes você vê em tempo real:

Cota usada hoje (barra de progresso por sessão)
Status de warmup ("Dia 12/35", "Aquecido")
Cooldown ativo (badge amarelo)

Em /app/logs filtra por status = FAILED pra investigar.