WhatsApp new-chat cap
See the new-chat cap WhatsApp set for a linked-device number and how Polymorfa paces sends to it.
WhatsApp can cap how many new chats a linked-device number starts in a cycle. WhatsApp decides this per number. Most numbers have no cap. When WhatsApp has not enabled a cap for a number, Polymorfa changes nothing about how that number sends.
When WhatsApp has enabled a cap, Polymorfa reads the number's limit, how many new chats it started in the current cycle, and when the cycle resets, and holds back sends that would start a new chat while the number is capped. Messages to people who already have a chat with the number are never held.
What counts as a new chat#
A new chat is a one-to-one chat with a person that WhatsApp does not already treat as an existing chat for your number. WhatsApp treats a chat as existing for about four weeks after the person last messaged your number. Groups, broadcasts, channels and your own number never count.
Where the numbers come from#
Every value comes from WhatsApp:
- whether a cap applies to the number, from WhatsApp's configuration for it;
- the limit, usage, status and cycle, which WhatsApp reports when the number opens a new chat and whenever it updates them.
Polymorfa does not count new chats itself, and it does not estimate a limit WhatsApp has not reported. Until WhatsApp reports a cycle, the limit and usage are null.
WhatsApp reports one of four statuses: none, first_warning, second_warning and capped. The warnings come from WhatsApp before the number reaches its limit. When the reported cycle ends, the status reads none until WhatsApp reports the next cycle.
Read the cap for a number#
Get session returns newChatCapping for a linked-device number.
curl https://api.polymorfa.com/platform/sessions/support-line \
-H "Authorization: Bearer $POLYMORFA_API_KEY"const number = await messaging.sessions.retrieve("support-line");
console.log(number.data.data.newChatCapping);TypeScript:
The NewChatCapping type is in the SDK release that follows this API change.
{
"data": {
"sessionId": "support-line",
"type": "linked_device",
"status": "CONNECTED",
"newChatCapping": {
"enabled": true,
"pacing": true,
"status": "first_warning",
"capped": false,
"limit": 50,
"used": 26,
"remaining": 24,
"cycleStartsAt": "2026-09-01T00:00:00.000Z",
"resetsAt": "2026-10-01T00:00:00.000Z",
"observedAt": "2026-09-24T10:00:01.000Z"
}
}
}| Field | Meaning |
|---|---|
enabled | true when WhatsApp enabled a cap for this number, false when it did not. null when WhatsApp's configuration for the number cannot be read to a decision; Polymorfa then does not pace to a cap. |
pacing | true when Polymorfa is holding back new-chat sends for this number while it is capped. It is true only when enabled is true. |
status | The status WhatsApp last reported, or null before WhatsApp reported one. |
capped | true while WhatsApp reports the number capped, pacing is true, and the reported cycle (or Polymorfa's hold) has not ended. Polymorfa holds back new-chat sends only then. |
limit, used, remaining | New chats allowed in the cycle, started in the cycle, and left, as WhatsApp reported them. |
cycleStartsAt, resetsAt | The current cycle, when WhatsApp reported it. While Polymorfa holds the number after WhatsApp rejected a new chat without reporting a cycle, resetsAt is the end of that hold. |
observedAt | When Polymorfa last observed this state. |
newChatCapping is null until Polymorfa has observed the number, and it is absent for official WhatsApp Business numbers and from List sessions.
What happens while a number is capped#
A send that would start a new chat is refused before it reaches WhatsApp with 429 and new_chat_limit_reached. The Retry-After header gives the seconds until the cycle resets when WhatsApp reported the reset time. The message.failed webhook for an asynchronous send reports error send_failed with the same code. Sends to existing chats continue.
In campaigns, a capped number leaves the sending pool until its cycle resets. Recipients are not dropped:
campaign.cap_reachedreports the number withcapTypenew_chat, the limit WhatsApp reported ascapLimit, and the cycle end aswindowResetsAt. When every number in the pool is capped, recipients stay queued and are tried again at least every five minutes;- when a send is refused because the number became capped between choosing it and sending, the recipient is queued again for another number and
campaign.throttledreportsreasonnew_chat_limit_reached.
While a number is near its limit, campaigns send more of the new chats through the numbers that have used less of theirs.
If WhatsApp itself rejects a new chat because the number reached its cap, the send fails with the same new_chat_limit_reached code. When WhatsApp enabled a cap for the number, Polymorfa then treats it as capped until the cycle WhatsApp reported ends, or for one hour when WhatsApp has not reported the current cycle, and campaigns defer its recipients as above. When WhatsApp did not enable a cap for the number, the send is a failed attempt and a campaign retries it like any other failure.