> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/connect/api/get-session) returns `newChatCapping` for a
linked-device number:

```bash theme={null}
curl https://api.polymorfa.com/platform/sessions/support-line \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"
```

```json theme={null}
{
  "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`](/api/errors#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](/guides/engage-at-scale/campaigns-and-bansafe), 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.