Skip to main content

Concepts

Instance (number)​

Each number is an instance with its own whatsmeow session, persisted and encrypted. It has a state machine with a reason: qr_pending → connecting → connected; drops are distinguished as transient (reconnects on its own), logged_out (rescan needed), and banned (out of rotation).

Rotation and anti-ban​

Several numbers form a pool with a strategy (round_robin, least_used, health_weighted). Sending without instance_id rotates automatically. Anti-ban: human-like throttling with jitter, "typing" presence, warming (growing limits on a fresh number), per-number proxy, and a health score — a bad number leaves the rotation immediately.

🔥 Warming — why it matters​

WhatsApp bans fresh SIMs that fire too early. That's why every freshly connected number goes through a warming period (default 5 days, configurable per account via warming_days): automatic rotation prefers already-warmed numbers to distribute volume, protecting your SIMs. It's a survival advantage — not an obstacle:

  • During warming, the number joins the rotation as a fallback: if it's the only one available (e.g. you just connected it), it still sends — tests and first sends work normally.
  • When already-warmed numbers exist, they are preferred for the bulk of the volume.
  • To force a specific number, pass instance_id on the send.
  • The API only responds 409 no_number_available when there is no connected/healthy number at all.

Recommendation: start slow on a fresh number and ramp up volume over the days — bZapper already applies growing limits automatically.

LID​

Contacts may arrive as @lid (a hidden identifier) instead of @s.whatsapp.net. The API normalizes this and exposes sender.lid in the envelope; detect mentions by JID, never by text.

Observability​

If a number drops, you know immediately: SSE (status changes live) + the instance.* webhook (with the reason) + an optional alert. Live health score and per-number/per-tenant metrics.

Honest caveats​

  • Buttons/lists are unreliable (worse in groups) → the API always sends an equivalent numbered text menu. In groups, text only.
  • Forwarding, labels, and starting a call are experimental (a whatsmeow limitation) and respond 501.
  • An active bot in many groups increases ban risk — respect throttling + proxy.