How sending protects your number

WhatsApp bans numbers that behave like bots, so every message goes out the way a person would send it, and some wait or are refused. A refused message has status failed and says why in error, in plain words, with a fixed error_code for your code. GET /v1/instances/{id} shows where an instance stands today, under protection.

In short#

• Replies go first. A message to someone who wrote to the instance in the last 24 hours goes within seconds, after "seen" and "typing…". Replies are never held by the new-people limits, warm-up or quiet hours. They still keep their pace (a few seconds apart, within the instance's 20 messages a minute) and the per-person cap, count toward your plan, and are refused after the person wrote "STOP", until they write again.
• People who never wrote are limited. Messages to them are spaced out, capped per day, and not sent at night.
• So let people write first. Each instance has a chat_link in GET /v1/instances/{id}: a wa.me link that opens a chat with it (add ?text= for a greeting already typed). Put it on your website, receipts and signs. Your panel makes the link and its QR code too ("Chat link" on the Instances page). People who write first are replies: they go within seconds and keep your instance safest.

The rules#

• New people. Someone who never wrote to the instance is messaged 30 to 60 seconds apart, with a break every 10, and not between 22:00 and 08:00 (or the quiet hours you set) in the instance's local time: the time zone of its phone's country, or of its area code in the US, Canada, Brazil and Mexico, shown as protection.timezone (ask us if it is wrong). Its day, for every daily limit, starts at midnight there too. A newly linked instance may message 10 new people a day, rising to 50 over its first two weeks. Someone in another country counts as two. Someone who wrote to the instance in the last 90 days does not use one of the day's new people, also after their messages are deleted. Every other rule for someone new still applies to them.
• Warm-up. For its first two weeks after linking, an instance may send 50 messages a day that are not replies (to people who wrote more than a day ago, to people who never wrote, to groups and channels), 100 from day 4 and 200 from day 8, with no cap from day 15. Replies always go, and are never counted. Your panel shows the warm-up on the instance's page, day by day, with what to do to earn WhatsApp's trust. Past it, a message fails with the reason; protection.not_replies_today and protection.not_replies_limit show where the instance stands (the limit is null once it has warmed up, unless you set your own not_replies_per_day).
• The limit adapts. It is halved when WhatsApp warns the instance, or when few of the people it messaged first answer. New chats pause when WhatsApp restricts the instance or it nears or reaches WhatsApp's quota of new chats, for an hour after WhatsApp refuses one, and when almost nobody answers. Replies are never paused.
• When WhatsApp refuses. While WhatsApp restricts the instance, and for the rest after it refuses one of its messages (at least an hour), everything but replies waits: messages to people who wrote more than a day ago, follow-ups, groups and channels, as well as new chats. Each waits until it ends when that is within 6 hours; otherwise it fails with the reason. Replies to people who wrote in the last day still go.
• In order. Messages from one instance to one person go in the order you sent them, so a reply queued behind a message that is waiting its turn waits with it.
• No flooding one person. At most 4 messages an hour to someone who has not answered (10 while they are chatting with you); the next waits.
• Wait for an answer from someone new. Someone who never wrote gets at most 3 messages a day: the first one and two more (a text and its file, then one reminder). Further messages that day fail with the reason. If they still have not answered, none of your instances writes to them first again until 7 days after the last message any of them sent (messages your team typed on the phone count): a first message before then fails with the date it may go. Once they write back to any of your instances, none of this applies.
• Opt-outs. Someone whose whole message is "STOP" (or "unsubscribe", "end", "quit", "remove me", "do not message me", "إلغاء الاشتراك", "توقف", "وقف", "وقف الرسائل", "لا تراسلني", "مش عايز رسايل") gets nothing more from any of your instances until they write again. A message within ten minutes of it does not count, nor does a short one that still says stop ("I said stop!"), nor an edit of an old message. Once they write again you can answer and message them as before, and a question that merely uses such a word ("When does the offer end?") is not a new opt-out. They stay out of broadcasts until their whole message is "START" (or "subscribe", "اشترك", "ابدأ"), to any of your instances.
• First messages: text or a file, not a location, a contact card, a sticker or a poll; no http:// links, not a link on its own, and at most 600 characters. The same text, or the same file with the same caption (or none), may open a chat with at most 5 new people a day across your instances, so make each one personal (their name, their booking or order). Say who you are and why you are writing.

The safety score#

protection.safety scores the instance from 100 down, every hour. level is good, attention or caution; reasons say what lowers it, each with its weight (the points it takes off): the instance's age, how the people it messaged first answered, WhatsApp's warnings and refusals, sends to numbers not on WhatsApp, people who asked it to stop, how much of what it sends goes to people who never wrote, today's use of its limits, and its profile. advice is the next step most worth taking. The score only warns; the rules above are what hold or refuse messages. When an instance drops to caution, your team is emailed with the reasons.

Your own settings#

Each instance's protection can be made stricter, or adjusted within safe limits, but never switched off: PATCH /v1/instances/{id} with protection_settings, or "Protection settings" on the instance's page in the panel. Send only what changes; null puts a setting back to the recommended value.

• Move and widen the quiet hours (at least 6 hours, always covering 00:00 to 05:00).
• Cap new people a day (2 at least, as someone abroad counts as two), and messages that are not replies a day, lower.
• Slow the gap between first messages (30 to 60 seconds at the fastest, up to 600) and lengthen the break after every 10.
• Allow fewer follow-ups to someone who has not answered (0 to 2), and wait longer before writing first again to them (reopen_after_days, 7 to 30 days).
• Leave chats unread when you reply (mark_read_before_reply).
• Say a phone is an established number with a long WhatsApp history, so its warm-up starts at day 8 instead of day 1 (never skipped: WhatsApp watches every newly linked device).

The keys:

A value past a safe limit is refused (422, with the reason) and nothing is saved. protection.settings shows the values in force, and customised lists the ones you changed. A message refused because of your own setting says so ("Your setting for this instance allows…"). Typing, the per-person cap, contacts abroad counting double, the first-message rules, opt-outs, groups and WhatsApp's warnings are the same for every instance.

Automatic warm-up (optional, in the instance's protection settings, or automatic_warmup in protection_settings): in their first two weeks, two or more of your instances chat with each other now and then, so each builds a history of normal use. It runs only between your own instances, each on its own address in its own country. Paying customers' instances get one; on a free trial they share ours, so it starts with your first payment. Those chats are real messages (an opening one uses one of the day's new contacts), but they are not in GET /v1/messages or GET /v1/chats, not sent to your webhook, never answered by your auto-replies, and never count toward your plan.