A whatsmeow alternative for running WhatsApp numbers for customers

whatsmeow is a Go library for the WhatsApp Web multi-device protocol, and among the libraries in this space it is one of the most complete. It gives you a client, a SQL session store, QR and phone pairing, typed events and proxy support, in one import. If you are weighing it against a hosted API, the library is rarely the problem. The problem is the service you have to build around it before a customer can depend on a number, and that is what this page is about.

#What whatsmeow gives you

whatsmeow lives at go.mau.fi/whatsmeow, is maintained by tulir, and is licensed under the Mozilla Public License 2.0. It has no tagged releases: you depend on a pseudo-version of the latest commit, and when we checked the last commit was two days old. Support is a Matrix room and a GitHub Discussions category, and the Go package docs cover every method and event.

Out of the box you get more than most libraries offer:

• A session store. sqlstore keeps device keys in SQLite or PostgreSQL, so sessions survive restarts without you designing a schema.
• Pairing both ways. GetQRChannel streams QR codes, and PairPhone returns a code to type on the phone.
• Typed events. *events.Message, *events.Connected, *events.Disconnected, *events.LoggedOut, *events.TemporaryBan, *events.StreamReplaced and more, through AddEventHandler.
• Reconnects. EnableAutoReconnect is on by default.
• Proxies. SetProxyAddress, SetProxy and SetSOCKSProxy, for the WebSocket and for media.

Its README lists what is not implemented yet, such as broadcast list messages and calls, and it does not carry a warning about bans. That is your responsibility, as it is on any stack.

#Who should run whatsmeow themselves

If you write Go and the list below reads like work your team already does, whatsmeow is a strong base.

• You run the whole product on your own infrastructure, for data residency or because it is what you sell.
• You need protocol features the day they land and would rather read the library's changes than wait for an API to expose them.
• You have a handful of numbers and a person who can look at them when something is off.
• You already operate residential proxies and an on-call rotation.

For a bridge, a personal bot or an internal tool, it is often the right answer. For numbers your customers pay for, keep reading.

#What a customer number needs beyond the library

A WhatsApp session lives on a bad network. Residential exits drop connections every few minutes, sockets go quiet without closing, and round trips jump from milliseconds to seconds. On top of that, WhatsApp forms an opinion of each number from how it connects and how it sends. The library handles the protocol. Each item below is something you build and run around it, next to what wuapi does, with the values from our code.

#Where each number connects from

A library proxy setter answers how. It does not answer which exit, in which country, for how long, and what to do when it fails.

Yours to build: a residential proxy account, an exit per number in its owner's country, sticky assignment, health checks, and a rule for when the proxy is down.

What wuapi runs: each account is created with a proxyLocation from 134 countries. The engine tests three candidate exits before a number first logs in through a new one and keeps the fastest, and holds that exit across reconnects and restarts. If the proxy is unreachable the number stays offline. There is no fallback to a datacenter address or a direct connection. Each paid number includes 0.5 GB of traffic a month, then $0.99 per GB.

#Changing exits on a budget

An exit that changes too often is a signal of its own. Why WhatsApp bans numbers covers the network side.

Yours to build: a rotation policy, and a way to tell a dying exit from a provider outage.

What wuapi runs: a number rotates only after 3 failed connects, no more than 4 times a day and at least 6 hours apart, never past 8 a day. When a proxy gateway fails for several numbers at once, new connections move to a gateway in another region, and move back once the first recovers, without touching live sockets or spending any number's budget. Sessions use SOCKS5 by default because we measured it to stay up better than HTTP tunnels.

#Telling a dead socket from a slow one

Yours to build: liveness checks beyond the protocol's keepalive, and a deadline on every network wait.

What wuapi runs: a liveness ping with an adaptive 6 to 20 second deadline, a keepalive with a hard limit, and a 20 second deadline on WhatsApp's acknowledgement of a send, past which the connection is recycled. The replacement is dialed ahead.

#Reconnecting the right amount

whatsmeow reconnects on its own. The policy around it is yours: when to recycle, when to rebuild, and when to stop.

Yours to build: backoff, a rebuild path, and a hard stop on terminal events.

What wuapi runs: an immediate first retry, then exponential backoff with full jitter capped at 20 seconds, recycling the connection in place before rebuilding the session after two failures. No reconnect at all after logged_out, connection_replaced or temporary_ban; one version refresh on client_outdated. If many numbers drop together, the engine treats it as a network incident and spreads reconnects out.

#Never two sockets for one device

Two processes holding the same session look like a takeover, and WhatsApp logs the device out.

Yours to build: a single-writer rule across your processes, encrypted backups of the store, and a way to move a session to another machine.

What wuapi runs: sessions are encrypted with AES-256-GCM before they are stored, restorable on another worker without a new QR code, with fenced writes so an old worker cannot overwrite a newer session. Deploys move sessions one at a time.

#Sending without losing or doubling

Yours to build: a per-number queue that survives drops and restarts, and deduplication.

What wuapi runs: one message at a time per number. A send made during a drop waits for the number and is retried with the same WhatsApp message id, so it cannot be delivered twice. Your own retries are covered by an Idempotency-Key kept for 24 hours.

#Checking before writing to a stranger

Yours to build: a registration lookup before a first message, and a cache.

What wuapi runs: an always-on check before any first message to a contact, failing with not_on_whatsapp when the number is not registered, with answers cached for 7 days (yes) or 6 hours (no).

#Pacing

Yours to build: rate limits per number, a stricter one for new contacts, and a typing indicator.

What wuapi runs: a per-minute cap up to 30 with a random 1 to 3 second gap, a first-contact cap, and typing sized to the message. Off by default, so replies go out at once; we recommend 12 a minute and 5 to new contacts for outbound. Keep your number healthy says when.

#Everything your product talks to

Yours to build: an HTTP API for the rest of your stack, events, media, logs and alerts.

What wuapi runs: a REST API with an OpenAPI 3.1 file, a TypeScript SDK and an MCP server. Webhooks signed with HMAC-SHA256 over the timestamp and body, retried at 30s, 2m, 10m, 1h and 6h. Media sent by URL, fetched once up to 100 MB. A 20 second grace before account.disconnected, and email or Slack when a number stays offline past your threshold.

#The work, side by side

#Moving from whatsmeow

container, _ := sqlstore.New(ctx, "sqlite3", "file:wa.db?_foreign_keys=on", nil)
device, _ := container.GetFirstDevice(ctx)
client := whatsmeow.NewClient(device, nil)
_ = client.SetProxyAddress("socks5://user:pass@proxy.example.com:1080")
client.AddEventHandler(func(evt interface{}) {
	switch v := evt.(type) {
	case *events.Message:
		// reply, queue, dedupe, pace...
	case *events.LoggedOut, *events.TemporaryBan:
		// stop, alert, do not reconnect
		_ = v
	}
})
_ = client.Connect()

On wuapi the same program is an HTTP handler that verifies the signature and calls POST /v1/messages, from Go with net/http or a client generated from the OpenAPI file.

Each number links again, since a session in your store cannot be imported into ours. Verify deliveries as the docs show. The Free plan gives you 1 number and 2,000 messages a month with no card to test against your own service.

#Questions people ask