Protecting your number (Number Shield)
How the Number Shield governs every send — warm-up caps, pacing, quiet hours, opt-outs, content rules — and what the API answers when it queues, paces or refuses.
Every message, from the dashboard, the inbox, campaigns, OTP or the API, goes through the Number Shield. It lowers the risk of WhatsApp restricting your number; no tool can promise a number is never restricted. It can’t be switched off, and you can only make it stricter.
What it checks
- Warm or cold. People who wrote to the number in the last 24 h are warm (fast replies); everyone else is cold (paced, capped).
- Warm-up caps for cold messages, growing with the number’s age and health (table below).
- Pacing between cold messages (≈ 8–25 s with short breaks); replies to warm chats wait 1–3 s.
- Quiet hours for campaigns (default 22:00–09:00).
- Opt-outs. Someone who sent an opt-out keyword («إلغاء», “stop”…) is on your suppression list.
- Content rules. No URL shorteners; no links to new contacts from numbers younger than 7 days; the same text to more than 50 new contacts in 24 h is refused.
| Stage (since first connection) | Cold per day | Cold per hour |
|---|---|---|
| Days 1–3 | Cold per day20 | Cold per hour10 |
| Days 4–7 | Cold per day50 | Cold per hour15 |
| Week 2 | Cold per day100 | Cold per hour25 |
| Weeks 3–4 | Cold per day200 | Cold per hour40 |
| Mature (30+ days, good health) | Cold per day400 | Cold per hour60 |
What your request gets back
| Outcome | Answer | What to do |
|---|---|---|
| Sent | Answer200, status: "sent" | What to doTrack it with message.status. |
| Queued (busy number / short pacing) | Answer200, status: "queued" + estimatedDelayMs | What to doNothing — it leaves on its own; message.status follows. |
| Paced | Answer429 SAFETY_PACING + details.retryAt | What to doRetry at retryAt, or use a campaign. |
| Cap reached | Answer429 SAFETY_HOURLY_CAP_REACHED / SAFETY_DAILY_CAP_REACHED | What to doWait until retryAt (next local hour / midnight). |
| Number paused | Answer423 SAFETY_NUMBER_PAUSED + Retry-After | What to doReplies to warm chats still work; the rest waits. |
| Refused | Answer422 SAFETY_SUPPRESSED / SAFETY_CONTENT_BLOCKED (details.reasons) | What to doDon’t retry unchanged: remove the recipient or change the content. |
| Banned | Answer403 SAFETY_NUMBER_BANNED | What to doNothing can be sent from this number. |
Your controls
GET …/health— score, level, reasons, warm-up stage, caps, today’s usage, restrictions.POST …/pause— pause the number for 5 minutes to 7 days (e.g. while you investigate complaints). You can lift your own pause, never a protective one.PUT …/limits— stricter daily / hourly caps or a longer gap. The stricter value always wins.number.restrictedandcampaign.statuswebhooks tell you when WhatsApp or the Shield stepped in.