Skip to content
Shortcut: /, ⌘K or Ctrl+K

Turn on the warm-up plan

Give every Number in a project a daily message allowance that grows over its first weeks and shrinks when its Health falls.

View as Markdown

A new WhatsApp Number that sends hundreds of messages on its first day is the pattern WhatsApp restricts fastest. The warm-up plan gives every Number in a project a daily allowance that starts small, grows over the Number's first weeks and shrinks when its Health falls.

The plan is off until you turn it on. Turning it off is always allowed.

Before you begin#

  • The warm-up plan is part of BanSafe Lite, included on Standard and Pro Numbers. Turning it on is refused with warmup_plan_not_entitled when no Number in the project is on one of those tiers. See Number tiers.
  • In the Console, you need the owner or admin role on the team to change the plan. Members can read it.
  • Through the API, use a team key or project token with sessions:manage to change it and sessions:read to read it.

How the allowance works#

Each Number gets one allowance per day, from its age and its Health band:

  • On its first day a Number may send 20 messages.
  • The allowance grows in a straight line to the daily cap of 2,000 over 14 days.
  • The Health band scales the result: good keeps all of it, fair three quarters, poor half, failing a quarter. A Number without a fresh estimate keeps all of it, because the ramp is already cautious.
  • The allowance never falls below the first-day figure or rises above the cap.

A Number seven days in with good Health may send 1,010 messages that day; with poor Health, 505. You can change the first-day figure and the length of the ramp. The 2,000 daily cap per Number is fixed, and campaigns already obey it.

The allowance resets at midnight in the Number's own country, worked out from its phone number.

How Polymorfa counts a Number's age#

The ramp counts from the earliest proof the Number was active: when it was linked, or its oldest message in history if that is earlier. A Number with no such proof starts the ramp on the day you turn the plan on. The Number's Health response reports this as tenureSource: history, link or plan, or null when the evidence cannot be classified.

Turn on the plan#

Console

  1. Open the project's Safety page, select Settings and find Warm-up plan.
  2. Turn on Warm-up plan on for this project.
  3. Set Messages on the first day (1 to 2,000) and Days to reach the cap (1 to 90). The Console draws the ramp as you change them.
  4. Select Save warm-up plan.

API

Send only the settings you want to change:

Shell
curl -X PUT "https://api.polymorfa.com/platform/projects/$PROJECT_ID/warmup-plan" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "warmupDays": 14, "dailyStart": 20 }'
FieldValues
enabledtrue or false
warmupDays1 to 90
dailyStart1 to 2,000

The Messaging API serves the same setting at /messaging/projects/{projectId}/warmup-plan. See Update the warm-up plan.

The response carries the plan, the cap and the allowance by day for a Number with good Health:

JSON
{
  "projectId": "3f9c...",
  "plan": { "enabled": true, "warmupDays": 14, "dailyStart": 20 },
  "ceiling": 2000,
  "curve": [
    { "day": 0, "allowance": 20 },
    { "day": 1, "allowance": 161 },
    { "day": 7, "allowance": 1010 },
    { "day": 14, "allowance": 2000 }
  ],
  "entitled": true,
  "entitlementReason": null
}

The plan is stored before any Number is told about it. If a connected Number does not confirm it, the request returns 503 propagation_pending; the plan is already stored and Polymorfa keeps delivering it.

If the project loses BanSafe Lite while the plan is on, you can still turn it off. Turning it on again needs a tier that includes it.

Check a Number's allowance#

Console

Select the Number on the Safety page and open Activity. Warm-up plan for this number shows Allowed today, Sent today, Day of the ramp and when the allowance Resets. Ramp starts from names the evidence: Message history, Link date or Plan start.

API

API Get ban safe health carries a warmup block:

JSON
{
  "warmup": {
    "enabled": true,
    "tenureSource": "history",
    "tenureDay": 7,
    "allowance": 1010,
    "sentToday": 640,
    "resetsAt": "2026-09-08T03:00:00.000Z",
    "curve": [{ "day": 0, "allowance": 20 }]
  }
}

When the project has no plan, enabled is false and allowance is null: there is no ceiling, rather than a ceiling of zero.

sentToday reads 0 until the first send of the day.

What happens at the allowance#

Just before each send, Polymorfa reserves one slot in the Number's allowance for the day. Concurrent sends and restarts share the same count, so the final slot is never spent twice. A reserved slot stays counted even if the send then fails or its result cannot be confirmed.

WhereWhat happens
Messaging API sendAllowance used up: 429 bansafe_daily_allowance_reached with the seconds until reset. Slot not confirmed: 503 bansafe_accounting_unavailable with retryAfter: 5. Another attempt already holds a slot for this send: 409 bansafe_send_outcome_unknown.
Webhookmessage.failed carries the same code. Allowance and accounting refusals use error: "blocked_by_safety"; an unknown outcome uses error: "send_failed". Retryable failures include retryAfter.
CampaignsThe recipient waits for the next reset, or is requeued after at least five seconds when the slot could not be confirmed. An unknown outcome fails the recipient without a retry.

To handle these responses:

  • After 429, send the message again after the reset. Nothing changes on the Number and no restriction is applied.
  • After 503, retry the same message after retryAfter seconds, one retry at a time.
  • After 409, do not retry automatically. Check the message's delivery state before you decide to send a new one.

Creating a group and adding people to one do not count against the allowance; safety limits still apply. Test numbers do not use an allowance. The smallest of the allowance, the Number tier's throughput, a campaign's own pacing and any restriction wins.

See also#