WhatsApp new-chat cap

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"

{
  "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_reached reports the number with capType new_chat, the limit WhatsApp reported as capLimit, and the cycle end as windowResetsAt. 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.throttled reports reason new_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.

Get started

Tools and clients

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

WhatsApp new-chat cap

What counts as a new chat

Where the numbers come from

Read the cap for a number

What happens while a number is capped

​What counts as a new chat

​Where the numbers come from

​Read the cap for a number

​What happens while a number is capped

What counts as a new chat

Where the numbers come from

Read the cap for a number

What happens while a number is capped