Set a Health rule and handle restrictions
Stop, slow or log out a Number when its Health drops, report a ban, and tell your own actions apart from WhatsApp's.
A Health rule acts on a Number when its Health falls below a score you choose. This page shows how to set one, how to read what it did, and how to handle a restriction from Polymorfa or from WhatsApp.
Polymorfa keeps three facts apart, and so should your integration:
| Fact | Where you read it |
|---|---|
| Health, an estimate of the Number's state | Health |
| An action your project rule or Polymorfa applied | Health rule activity, API List ban safe enforcement |
| A restriction observed from WhatsApp | bansafe.incident, the Number's incident history |
Low or unknown Health does not prove that WhatsApp restricted a Number.
Before you begin#
- In the Console, you need the owner or admin role on the team to change a rule. Members can read it.
- Through the API, use a team key or project token with
sessions:manageto change a rule andsessions:readto read it. - To send the webhook, the project needs an enabled, project-wide native webhook subscribed to
bansafe.health_thresholdor to all events. See Webhooks.
Set a Health rule #
Each project has one rule. It is off until you enable and save it. The rule acts only on a fresh, available estimate below the threshold: a score equal to the threshold, unknown Health and stale evidence trigger nothing.
| Action | API value | What happens |
|---|---|---|
| Notifications only | none | The Number keeps running. Polymorfa sends the notifications you chose. |
| Stop the number | stop | The Number disconnects and keeps its linked credentials, so you can start it again. |
| Slow down sending | slow_down | Outbound sending is capped at the messages-per-second value you set. |
| Log out | log_out | The Number is unlinked. Pair it again before it reconnects. |
Email and webhook notifications can accompany any action. An enabled rule needs an action or at least one notification.
Console
- Open the project's Safety page and select Settings.
- Under Health rule, turn the rule on and move the slider to the threshold, a Health value from 0 to 100.
- Choose an action. For Slow down sending, enter the messages per second.
- Select email, webhook or both. The webhook option stays disabled until the project has a matching webhook.
- Select Save Health rule.
If someone saved a newer version first, the Console keeps your edits and asks you to reload the saved rule before trying again.
API
Read the rule to get its version, then replace it with that version:
curl -X PUT "https://api.polymorfa.com/platform/projects/$PROJECT_ID/health-policy" \
-H "Authorization: Bearer $POLYMORFA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": 3,
"enabled": true,
"threshold": 40,
"sessionAction": "slow_down",
"slowDownMps": 1,
"emailNotification": true,
"webhookNotification": false
}'Every field is required. A version that no longer matches the stored rule is refused, so read again and retry with the new version. See Update the Health policy.
Saving a rule does not act on any Number at that moment. It governs the next Health evaluations.
Pacing rates #
slowDownMps must be greater than zero and no higher than the project's sending limit: the lowest throughput among the project's default Number tier and the tiers of its Numbers (5, 10 or 100 messages per second for Free, Standard and Pro). The Console and the API refuse a higher value rather than lowering it for you.
Check what the rule did#
Console
Open the Activity tab on the Safety page. Each row of Health rule activity shows the Number, the action, its status or outcome, the Health and threshold that triggered it, the estimator and the completion time. The history stays after a rule stops or logs out a Number.
API
curl "https://api.polymorfa.com/platform/bansafe/health-actions?projectId=$PROJECT_ID" \
-H "Authorization: Bearer $POLYMORFA_API_KEY"Filter by session or status. Results are newest first and use cursor pagination. See List Health actions.
An outcome is one of applied, cleared, notification_queued, superseded, expired, not_applied or delivery_failed. Polymorfa checks the latest Health again before it applies a queued action.
Polymorfa restrictions#
Polymorfa can also limit a Number's sending. The Console shows a banner above the Number's findings that names the limit and what remains before it lifts, for example: "This lifts after 48 hourly safety checks meet the restriction's recovery threshold. 12 of 48 done, and 2 findings must resolve first."
Read restrictions with API List ban safe enforcement. state: "applying" means the restriction is stored and the connected Number has not confirmed it yet; Polymorfa keeps delivering it. A restriction stays in force until it is lifted. See List enforcement.
Appeal a restriction#
- Acknowledge every open finding on the Number. See Acknowledge a finding.
- Open the Number on the Safety page and, under Findings, select Appeal this restriction.
Appeals are available in the Console to team owners and admins. Filing an appeal does not lift the restriction, and neither does acknowledging a finding. Health changes after new evidence; a restriction lifts when its recovery conditions are met.
WhatsApp restrictions#
bansafe.incident reports a restriction observed from WhatsApp, or one your team reported, when it is recorded and again when it settles. It does not mean Polymorfa applied an action. A stopped or slowed Number keeps its own observed account state, shown with its timestamp and source.
session.restriction_updated reports one WhatsApp restriction as it starts and ends: the limit on starting conversations and calls with people the Number has not chatted with. While it is active, Polymorfa refuses calls to those people with number_restricted. See Calls.
With a team key, list the team's recorded bans with API List session bans and the bans in force with API List active session bans.
Report a ban#
When WhatsApp bans or restricts a Number and Polymorfa did not observe it, report it so it is kept with the Number's history. A report becomes an observed incident. It does not set or replace Health. On a Pro Number, it also opens a Ban Credit claim.
Console
- Open the Number on the Safety page.
- Select Report a ban at the top of the Number's view.
- Enter the date it happened and an optional note, then confirm.
API
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents" \
-H "Authorization: Bearer $POLYMORFA_API_KEY" \
-H "Idempotency-Key: ban-report-sales-1" \
-H "Content-Type: application/json" \
-d '{ "session": "sales-1", "occurredAt": "2026-09-06T09:00:00Z", "note": "Number banned during outreach" }'session is required; note accepts up to 500 characters. Retrying with the same Idempotency-Key for the same Number returns the original report with created: false. Reusing the key for another Number returns 409 bansafe_incident_idempotency_scope_conflict.
Read reported and observed incidents with API List ban safe incidents. To withdraw your own report, call API Retract ban safe incident with a team key. An incident observed from WhatsApp cannot be withdrawn and returns 409 bansafe_incident_not_a_report.