Skip to content
WhatIsUp.dev

Keeping numbers healthy

WhatsApp restricts and bans numbers by how people react to them. A number that mostly answers people who wrote to it lives for years; a number that mostly messages strangers gets reported, restricted and then banned — often together with every other number that behaved the same way. This guide is what to do about it, and the tools the gateway gives you for each step.

On by default: health score and warnings

You don't have to configure anything to start. Every number gets a health level — good, warning, danger or restricted — recomputed every 15 minutes from the last 7 days: how many people it messaged first, how many of them replied, how new the number is, and what WhatsApp itself reports. You see it as a badge on the channel list, a banner on the channel page, the channel.health webhook and an email when a number turns danger or restricted. Read it with GET /v1/channels/{id}/health.

Auto-protect (off unless you switch it on, per number in its settings or with PUT /v1/channels/{id}/pacing) acts on it: messages to people who never wrote to the number are spaced out — a couple of seconds when healthy (a lone message still goes out at once), 30–90 seconds with "typing…" at warning, 2–5 minutes at danger and at restricted. Replies are never delayed, and the gateway never refuses or slows a send on its own over a number's health — it warns, and your traffic goes out at your pace. The rest of this guide is how to stay out of warning in the first place.

What gets a number banned

  • Messages to people who never wrote to you. Cold first contact is the single biggest signal, and WhatsApp counts it per number.
  • People blocking or reporting you. A few percent of recipients reporting a number can be enough.
  • The same text to many people. Identical templates across numbers link them together.
  • Nobody replying. A healthy number gets answers; one-way traffic looks like a broadcast.
  • Brand-new numbers at volume, and many numbers on one IP address.

1 — Let people write first

The safest message a number can send is a reply. For verification codes, flip the flow: instead of sending the code, show a button that opens WhatsApp with the code pre-filled, and let the person send it to you.

https://wa.me/5511999990000?text=My%20code%3A%20482913

You receive it as a message.received webhook, match the code, mark the number verified and answer on the same chat ("✅ Verified!"). Keep the outbound code only as a fallback.

2 — If you must message first

  • Only message numbers that asked for it. Confirm the number before sending ("Send the code to (11) 9••••-0000?"), rate-limit the button, and resend the same code instead of a new message each tap.
  • Ask for a reply. End with something like "Reply OK if this was you". Replies are the strongest "this is wanted" signal there is.
  • Vary the text, name the sender, and keep links out of first messages.
  • Don't retry dead numbers. A 400 undeliverable_recipient means the number has no WhatsApp — mark it invalid, don't send it through another number.
  • Budget new chats by number age. Conservative starting points: under 7 days, replies only; 7–14 days, up to 10 new chats a day; 15–30 days, up to 25; older, up to 40. When every number is at its budget, fall back to another channel (email, SMS) instead of pushing harder.
  • Stick a person to one number. Route the same recipient to the same number every time instead of spraying them across several.

3 — Watch what WhatsApp says about each number

WhatsApp tells the gateway how close a number is to its new-chat quota, and when it has temporarily blocked the number from messaging new people. Read it with GET /v1/channels/{id}/limits or subscribe to the channel.limits webhook:

{
  "new_chats": { "status": "first_warning", "used": 34, "quota": 50, "cycle_ends_at": "2026-10-28T21:09:00.000Z" },
  "restriction": { "active": false, "ends_at": null, "reason": null },
  "checked_at": "2026-10-25T18:05:00.000Z"
}

Treat first_warning as "slow this number down now": route its new conversations to another number until the status is back to none. While a restriction is active — or the number is capped until its cycle ends — WhatsApp refuses messages to people who never wrote to it. The gateway still sends them; each such send's 202 carries a warning, so you can move that conversation to another number:

{
  "message_id": "3EB0C431D5A8F2E91B7C",
  "client_ref": null,
  "status": "sent",
  "warnings": [
    {
      "code": "new_chat_restricted",
      "message": "WhatsApp has blocked this number from messaging new people until 2026-10-27T14:05:00.000Z. …",
      "ends_at": "2026-10-27T14:05:00.000Z"
    }
  ]
}

A message WhatsApp refuses turns failed (message.status webhook). Replies are unaffected. new_chat_capped is the same warning for a used-up quota.

4 — Pace your sends

Give a number a random pause between messages and a "typing…" indicator before each, so it sends like a person:

curl -X PUT https://api.whatisup.dev/v1/channels/$CHANNEL_ID/pacing \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "min_gap_seconds": 20, "max_gap_seconds": 90, "typing": true }'

Paced sends are queued (202 with status: "queued") and go out one at a time; time spent waiting never counts against the queue's expiry. A single send can carry its own typing_time (seconds) instead.

5 — One IP per number

By default every number reaches WhatsApp from the gateway's own addresses. Give each number its own proxy so one flagged number doesn't drag others down:

curl -X PUT https://api.whatisup.dev/v1/channels/$CHANNEL_ID/proxy \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "socks5://user:pass@203.0.113.7:1080" }'

Use a static (sticky) residential or mobile IP in the number's country — one per number. Free and datacenter proxies are shared and already flagged. The proxy is tested before it's saved; the test warns about rotating_ip (the address changes between connections) and country_mismatch. There is no fallback: while a proxy is set, the number connects only through it, and a proxy failure shows as proxy_error on channel.disconnected.

6 — Warm up new numbers

Before a new number sends at volume, give it a real profile (name, photo, about) and real conversations with people who answer — not only with your other numbers. Start with replies, then grow the daily new-chat budget week by week.

Checklist

  • Verification codes use the "send it to us" link; outbound codes are the fallback.
  • Numbers are confirmed and rate-limited before any first message.
  • Every first message asks for a reply and carries no links.
  • New chats per number stay within the age budget.
  • channel.limits is subscribed and first_warning takes the number out of rotation.
  • Sends are paced; each number has its own static proxy in its country.