Why WhatsApp bans numbers, and what to do about it

Nobody outside WhatsApp knows exactly how it decides to restrict a number. That sentence is the honest one, and this post is careful with it. What follows is the part that is enforced in code on every account, the part that is up to you, and the four things to do in the ten minutes after a restriction lands.

#What a restriction looks like from your side

A restricted number does not throw an error at the send. It goes quiet. The account drops with a reason, and the reason is the whole diagnosis.

None of these reconnect on their own. That is deliberate, and the reason is the important part of this post.

#What wuapi does, on every account

Eight things are enforced in code, not left to your discipline. Each one has a real value behind it.

• A pace on every number. 12 messages a minute per account, and 5 a minute to people who never wrote to it.
• A typing indicator first. The contact sees "typing…" for 0.8 to 6 seconds, longer for longer messages.
• A queue for bursts. Send 200 at once and they leave at the pace. A message waits up to an hour, then fails as rate_limited.
• A check before a first send. wuapi asks WhatsApp whether the number is on WhatsApp at all. If it is not, nothing goes.
• A residential exit. Each account connects from a residential address in the country and city you chose.
• A sticky address. It only moves after 3 failed connects, at most 4 times a day and 6 hours apart.
• No reconnect after a ban or a logout. Those two reasons stop the session for good.
• Calls declined on request. With rejectCalls on, every call is declined as it rings, with an optional text reply.

await wuapi.accounts.update(accountId, {
  pacing: { messagesPerMinute: 6 },
})
// null resets the account to the defaults

#What is up to you

The code handles the mechanics. It cannot decide who you write to.

• Write to people who expect you. They gave you their number and know why you are writing. Make stopping easy and honour it the first time.
• Let them write first when you can. A chat the contact started is the safest kind there is. A "message us on WhatsApp" link on your site does this for free.
• Warm up a new number. A new number sending a lot on day one is one of the most common causes of trouble.
• Write to one person, not a list. Use their name, their order, their appointment. The same text to hundreds of people tends to get reported.
• Keep the first message plain. No links or attachments in a first message to a new contact. Send them after they reply.
• Answer inbound quickly. Numbers that hold real conversations tend to look like people, because they are.
• Look like a business. Set a name, a photo and an about line before you send anything.
• Do not add strangers to groups. Share an invite link instead. A group you fill with people who did not ask is one of the fastest routes to a report, and group or community has the moderation tools that keep it clean.
• Keep the pacing alone. Raise it only for traffic to people who expect it.
• One number per use case. A bad week for support should not take sales with it.

Pace

12 messages a minute, 5 to new contacts

Typing indicator

0.8 to 6 seconds, scaled by length

Queue

up to an hour, then rate_limited

Exit rotation

after 3 failures, 4 a day, 6 hours apart

#A warm-up to start from

This is a suggestion from running numbers, not a WhatsApp limit. It is here because "send less at first" is easy to agree with and hard to do without a number.

A suggestion, not a rule. The code enforces the pace above; this is about volume, which only you control.

#Why a ban happens, and what it does to your code

A temporary ban does not fail your sends loudly. The account drops, the session stops, and your sends queue until they fail as account_offline. That silence is why a retry loop is so tempting and so wrong.

The last box is the whole lesson. The account is telling you not to reconnect, and the code that refuses to listen is why some bans never lift.

#The first four things to do

When a restriction lands, the order matters. Doing these out of order is how a temporary problem becomes a permanent one.

1. Stop sending from that number. Pause the queue, not only the API calls. A retry loop is the single worst move.
2. Do not re-link it. Each attempt is another signal. If it is a temporary ban, wait until it ends.
3. Read what went out. Who, how many, and what the text said, in the last few days. Logs are in the dashboard under Logs, Requests.
4. Start again at the warm-up pace when the number is back, not at the pace you were running before.

The account.disconnected webhook is retried six times on the usual schedule, 30s · 2m · 10m · 1h · 6h, so make that handler idempotent too. An alert that fires six times for one incident is the alert people learn to ignore.

#What does not work

Three things people try that make it worse or do nothing.

• A new proxy every send. Rotating a number's address constantly is a stronger signal than a stable one. The exit is sticky for a reason.
• Bulk to purchased lists. A list of people who never gave you their number is the most reportable thing you can do, and the proxy does not change that.
• Waiting it out silently. A number that stays idle for weeks is fine. A number that retries every minute is not.

#One number per use case, and why that is a safety feature

Keeping support, sales and alerts on separate numbers is usually advice about blast radius: a bad week for one does not take the others with it. It is also a safety measure, and that part is less obvious.

A restriction follows the number. If one account carries every message your product sends, then a bad afternoon in one function takes down support, sales and order notifications at once, and you have no healthy number left to see what happened from. Three numbers on three use cases means the surviving two keep working, and the restricted one is a data point rather than an outage.

It also makes the diagnosis possible. When each number has one job, the reply rate and block rate on each are a signal about that job. When one number carries all four, every metric is an average of four unrelated behaviours and tells you nothing.

The last row is the one worth arguing about internally. Marketing volume on a shared number is what turns a slow afternoon into a restriction, and separating it means the restriction, when it comes, costs you campaigns rather than support.

#The signals, before the restriction

Restrictions rarely arrive with no warning. Fewer replies and more blocks come first, and both are visible if you look.

• Reply rate falling across a cohort of contacts you message regularly.
• Blocks appearing on a number within a day or two of a send.
• Messages that used to deliver landing as failed with not_on_whatsapp, which usually means the number changed rather than the recipient's.
• Disconnects clustering on one number rather than spreading across your accounts.

A rise in blocks is the loudest one, and the one people are most likely to explain away.

#How to read the exit settings before you need them

The residential exit is doing real work, and it is worth knowing which two numbers on it are settings rather than facts.

The account connects from an address in the country and city you chose, and it stays on that address. It only moves after 3 failed connection attempts, at most 4 times a day, with 6 hours between moves, and at most 8 in a day when the exit keeps failing. Those bounds are the point: a number whose address changes on every reconnect is a stronger signal than one that never changes at all.

const account = await wuapi.accounts.get(accountId)
console.log(account.proxyLocation) // { country: "VE", city: "caracas" }
console.log(account.status) // "ready"

If the exit is down, the account stays offline. It does not fall back to a datacenter address, because a fallback would be a different number as far as WhatsApp is concerned. An account that cannot get a clean exit is an account you cannot send from, and knowing that is more useful than a send that silently works from the wrong place.

#What is not in wuapi's control

No guarantee, and no provider can give you one. wuapi links your number as a device and does not control WhatsApp, which can restrict any number at any time. The proxy removes a network signal and does nothing about what you send or how people react to it.

Support can help you read what happened and what to change. It cannot undo it. Anyone who says otherwise is selling you a promise about a system whose owner has not published the rules.

#Questions people ask

#Where to go next

The full guide is at keep your number healthy, with the same habits in a longer form. The WhatsApp QR code covers what happens when a number has to be linked again, and what a WhatsApp API costs covers the proxy line on the bill, which is where a media-heavy account's overage shows up.