Conceitos

Instância (número)

Cada número é uma instância com sessão whatsmeow própria, persistida e criptografada. Tem uma máquina de estados com motivo: qr_pending → connecting → connected; quedas distinguem transient (reconecta sozinho), logged_out (reescanear) e banned (fora de rotação).

Redundância e entrega

Vários números viram um pool com estratégia (round_robin, least_used, health_weighted). O envio sem instance_id rotaciona automaticamente. Entrega: controle de ritmo por número, ramp-up de volume (limites crescentes em número novo), proxy por número e health score — número ruim sai da rotação na hora.

🔥 Ramp-up de volume — por que importa

Números recém-conectados começam com limites de volume menores. Por isso, todo número novo passa por um período de ramp-up (padrão 5 dias, configurável por conta via warming_days): a rotação automática prefere números já em regime pleno para distribuir o volume. É um diferencial de sobrevivência — não um obstáculo:

• Durante o ramp-up, o número entra na distribuição como fallback: se for o único disponível (ex.: você acabou de conectar), ele ainda envia — testes e primeiros envios funcionam normalmente.
• Havendo números já aquecidos, eles são preferidos para o volume maior.
• Para forçar um número específico, passe instance_id no envio.
• A API só responde 409 no_number_available quando não há nenhum número conectado/saudável.

Recomendação: comece devagar num número novo e aumente o volume ao longo dos dias — o bZapper já aplica limites crescentes automaticamente.

LID

Contatos podem vir como @lid (identificador oculto) em vez de @s.whatsapp.net. A API normaliza e expõe sender.lid no envelope; detecte menção por JID, nunca por texto.

Observabilidade

Se um número cai, você sabe na hora: SSE (status muda ao vivo) + webhook instance.* (com o motivo) + alerta opcional. Health score vivo e métricas por número/tenant.

Caveats honestos

• Botões/listas não são confiáveis (pior em grupo) → a API sempre manda um menu de texto numerado equivalente. Em grupo, só texto.
• Encaminhar, labels e iniciar chamada são experimentais (limitação do whatsmeow) e respondem 501.
• Bot ativo em muitos grupos aumenta risco de ban — respeite throttle + proxy.