The per-number risk procedure
Run this against every number you operate, from the top down. Stop at the first row that matches: the rows are ordered so that an earlier answer makes the later ones irrelevant. Each input is something you can read from your own infrastructure or your own records.
| # | Check | If yes |
|---|---|---|
| 1 | Is the connection in requires_repair? | Re-pair now. The session will not come back on its own. If re-pairing fails, or the phone shows a restriction, go to row 2. |
| 2 | Does the primary phone show a restriction or ban notice? | Stop re-pairing. This is enforcement, not a session problem. Meta's bans page tells you to uninstall the unofficial client and use the official app. For an appeal, see WhatsApp's help pages on ban appeals. Nothing on the gateway side will fix it. |
| 3 | Is it suspended? | Decide deliberately. Someone paused it. Resume it or retire it, but do not leave it idle: the 30-day clock is still running. |
| 4 | Has the primary phone gone unused for 10 days or more? | Get the phone opened. At 14 days every linked device on that account logs out. This is a person picking up a handset, not an API call. |
| 5 | Has the number had no message activity for 25 days or more? | Schedule a re-pair before day 30. Do it at a time when an operator and the phone are both available. Do not send traffic to hold it open (see below). |
| 6 | Was the number linked to another unofficial client before you had it? | Treat it as higher risk. Meta's ban policy covers past links too. Keep it off critical paths until it has a clean history with you. |
| 7 | Is it degraded, disconnected or reconnecting? | Log it and wait. These recover on their own. Escalate only if the number moves to requires_repair. |
| 8 | None of the above | No action. Check again tomorrow. |
Two of these inputs you have to keep yourself. Last activity per number (row 5) is the newest message.received or message.sent timestamp you have stored for that connection. Last use of the primary phone (row 4) is not visible to any gateway, so it has to come from whoever holds the handsets. If you cannot answer either one for a number, treat that number as due.
One honest gap: Meta does not define what counts as “activity” for the 30-day rule, and it does not say whether inbound messages alone reset it. That is why row 5 schedules a re-pair instead of trusting traffic. A fresh link is the only action that definitely starts a new session.
The four rules, and the one that will cost you a number
Meta publishes these. They are specific, dated, and almost nobody outside WhatsApp knows them. From About linked devices:
Thirty days of inactivity. Linked devices are disconnected automatically after 30 days without activity. This is the one that catches people out, and the rest of this post is mostly about it.
Fourteen days without the primary phone. Linked devices work without the phone online, but they log out if the primary device goes unused for more than 14 days. A number whose owner was on holiday, whose phone sat in a drawer, comes back dead.
Four linked devices at a time. That is the cap. If you cycle test numbers, an old session you forgot about can occupy a slot.
A linked device cannot be primary. Windows, Mac, Web, iPad and wearables cannot become the primary device on an account. Your phone is the identity; everything else is downstream of it.
Note what is not in that list: Meta's linked-device rules say nothing about message volume or sending rate. That does not make volume safe. WhatsApp's Terms of Service govern how the service may be used, whatever client you link, so treat bulk or automated sending as a risk on any client.
Why a number you did nothing wrong still dies
Each number runs its own 30-day clock. Meta does not say exactly what counts as activity, but a number nobody is using is the obvious candidate: its session can quietly expire on a timer you never set.
This is the failure mode of a portfolio, and it does not look like a failure at all while it happens. A number with no traffic is not an error state. It is simply a number that stopped existing as far as WhatsApp is concerned, and the first person to find out is usually a customer asking why you did not reply.
The obvious mitigation — send a keepalive to every number on a schedule — is worse than the disease, in our judgment. Meta does not document that keepalives get numbers restricted, but they are automated traffic with no purpose, and that is the pattern its spam enforcement exists to catch. Meta has not documented an inactivity exemption, so there is no documented way to hold a session open indefinitely.
Habits the procedure depends on
The procedure is only as good as its inputs and the re-pair at the end of it. Three habits keep both honest. None of them is a daily check, so they sit here rather than in the table.
| Habit | Cadence | Why |
|---|---|---|
| Rehearse the re-pair | Once, then after any change to the flow | A re-pair on a number nobody is watching still needs a phone, an operator, and a session that is not already wedged. Do it on a test number before row 1 or row 5 asks you to do it for real. |
| Alert on state, not on errors | Set up once | A dead session still returns 200 to your webhook endpoint, so there is no error to alert on. Rows 1, 3 and 7 depend on you receiving connection.* events and storing the latest state per number. |
| Clear out stale linked devices | Monthly, and before linking a new number | The four-device cap is per account. A forgotten test session can occupy a slot and stop a real one from linking. |
And one thing not to do: never send keepalive traffic to hold a session open. It is the tempting fix for row 5, and in our judgment the wrong one: it is automated, purposeless sending, which is the pattern spam enforcement looks for.
Two failures that get called the same thing
When a number stops working, the reflex is to assume it was banned. That reflex is wrong most of the time, and it sends you looking for the one problem you cannot fix from the outside.
A session failure means the linked device stopped being linked. The account is fine. Re-scanning a QR code fixes it, and nothing is lost. Meta documents several independent causes, all of them routine.
An enforcement action means WhatsApp acted against the account. The number is restricted. For bans caused by unofficial apps, Meta's instruction is to uninstall the unofficial app and use the official one. No amount of re-pairing touches it.
The practical consequence: if you cannot tell them apart, you will spend your time re-pairing a number that was restricted, instead of dealing with the cause. Every article on this topic is about the second failure because that is what happens to Cloud API senders. Linked devices fail the first way, far more often, and it is barely written about.
What Meta documents about enforcement
The published position is short and absolute. About account bans for unofficial apps puts it plainly: using an unauthorized application or unsupported device violates WhatsApp's Terms of Service and can get an account banned. The clients you may link are named in About linked devices:
“Only link on WhatsApp Web, WhatsApp for Windows and Mac, WhatsApp Android Tablets, WhatsApp companion phones, or AI glasses. Linking your device through unofficial apps or websites may put your account at risk.”
And then the sentence that deserves more attention than it usually gets:
“Linking your account to an unofficial app or website, now or in the past, may result in a temporary or permanent account ban.”
The retrospective clause is the operative one. It means the relevant history is not only what you do this week — it is what a number was linked to before. If you are inheriting a number, that history came with it, and nothing you do now will change it.
It also means the enforcement surface is defined by WhatsApp's list of sanctioned clients, not by anything the gateway does internally. Whether a given tool is on that list is not something a third party can verify from the outside, which is why this post does not attempt to answer it for any particular product — including ours. Ask your provider what they link, and get a straight answer.
Triage: which failure you actually have
ChatRail models every connection as an explicit state and emits a webhook when it changes, so the two failures above are distinguishable rather than inferred. This is the table behind the product — the states and their permitted transitions live in apps/api/src/modules/connections/state-machine.ts.
| State | What it means | Human needed? |
|---|---|---|
connected | Session live. Nothing to do. | No |
degraded | Session impaired but usable. Sends may be slow or fail transiently. | No |
disconnected → reconnecting | Dropped, retrying on its own. This is the one people panic at. | No — it resolves |
requires_repair | The session cannot recover. The only state with no automatic path back to connected. | Yes — re-pair |
suspended | Paused deliberately. Nothing is broken, but nothing will change on its own either. | Yes — resume it |
The distinction that matters is which states a machine can fix. degraded, disconnected and reconnecting are all recoverable — the state machine exports them as such, and treating them as emergencies is how teams end up re-scanning QR codes that were working. requires_repair and suspended are the two that need a person, for different reasons: the first is broken, the second is paused. If you alert on one thing, alert on requires_repair — it is the one that represents a customer quietly losing a number.
Monitoring that catches this before a customer does
A number that dies silently is a support ticket you did not have to take. Five connection events cover it, one per state, and they are documented on the webhooks page:
connection.connected, connection.degraded, connection.disconnected, connection.requires_repair and connection.suspended.
Subscribe to connection.* and route on severity: page someone on requires_repair, open a ticket on suspended, and log the rest. degraded and disconnected are the early warning: a number that keeps cycling through them is likely to end up needing a human.
Two operational habits matter more than the alerting. First, make re-pairing a short-lived, operator-scoped flow rather than a support thread — the reconnection guide covers the boundary. Second, know which of your numbers have been idle: the 30-day rule is per number, so a portfolio of mostly-dormant numbers will lose them individually, on schedule, and a single dashboard will not make that visible for you.
What this post will not tell you
There is no reliable public data on how often linked-device accounts are enforced relative to Cloud API accounts, and nobody publishing a number is measuring the same thing you would be. Treat any figure you find — including the ones here — as anecdotal.
What is documented, and what this post sticks to: the four session-expiry rules above, the list of sanctioned clients, the retrospective clause, and the states your own infrastructure reports. Everything else is inference.
Related reading
Reconnect a dropped session · Webhook events · Linked Devices API · API reference