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"
}

A rotação vale pra todos os envios

O mesmo roteador é usado em POST /v1/messages, nas mensagens enviadas por automações (fluxos) e nos links redirecionadores /r/. Já POST /v1/contacts (criar contato/lead) não escolhe número nenhum — é só um registro; a rotação acontece no momento de enviar a mensagem. Por isso muitos leads novos se espalham entre os chips (lead novo → menos carregado) em vez de concentrar num só número e arriscar bloqueio.

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 e gradual da cota diária: ela sobe um pouco a cada dia, baseado na idade do chip.

Dias desde a 1ª conexão	Cota diária (aprox.)
0	20
7	~36
14	~52
21	~69
28	~85
35+	limite cheio do plano

A subida é linear (de 20 até ~100 ao longo de ~35 dias); a tabela acima são só pontos de referência. O ramp só limita pra baixo: se a sessão tem dailyLimit = 60, a cota nunca passa de 60. Depois de ~35 dias o número é considerado "aquecido" e recebe o limite cheio do plano.

A rampa acompanha a idade do chip: warmupStartAt é setado na 1ª conexão, e ligar/desligar o Modo seguro não reinicia o progresso (re-liga com base na data de criação do chip).

A cota só trava campanha pra número novo

O limite diário do warmup bloqueia apenas disparos de campanha pra números novos (que nunca conversaram com você). Conversas com números ativos, automações, mensagens via API (códigos/OTP) e o link de redirecionamento sempre passam, mesmo durante o aquecimento — eles só priorizam os chips abaixo da cota, mas nunca são barrados por ela. A única coisa que pode recusar um envio transacional é um chip em cooldown (falhando entrega), pra você poder cair num fallback em vez de a mensagem sumir.

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.