Skip to main content
BanSafe Health estimates the present state of eligible production Linked Device sessions on a 0–100 scale. Test numbers, Cloud API sessions, and simulated sessions do not receive an estimate. Higher is healthier. Each estimate describes the account at its recorded evaluation time. The launch estimator is rules_v1. It applies versioned rules to fresh operational measurements and reports the deductions behind the score. A learned estimator remains on the roadmap while Polymorfa collects production measurements and trusted account-state labels. Open Safety in Console, or call GET /platform/bansafe/health and GET /platform/bansafe/health/{session} with a sessions:read credential. Collection freshness and the source measurements have their own read surface. See Telemetry and collection.

​
What the response means

A valid estimate includes:
  • health, from 0 to 100;
  • band, derived from that estimate;
  • healthEstimatorVersion and healthEvaluatedAt;
  • healthFeatureCoverage, from 0 to 1;
  • healthSource: "rules_v1" and healthReliability: "rules_based"; and
  • healthExplanation, with bounded deductions and the evidence groups that were measured or missing.
For rules_v1, healthModelVersion, healthProbabilities, and mostLikelyHealthState are null. They remain in the response for a future validated learned estimator. Do not treat rules_based as model confidence. The displayed estimate can be older than the page load time. Read healthEvaluatedAt as the time Polymorfa last estimated Health.

​
When Health is unavailable

health is null and band is unknown when Polymorfa cannot return a supported present estimate. The response sets healthSource: "unavailable", healthReliability: "unavailable", and an unavailable reason when known: A response for a number that has never been evaluated has null Health metadata and no unavailable reason. Do not render null as zero: zero is the lowest valid Health estimate.

​
Observed account state is separate

observedAccountState reports a state Polymorfa directly observed through an account check or restriction event. It contains state, observedAt, and a customer-readable source. It is not inferred from Health, and Health is not replaced by the observed state. Recorded findings and Polymorfa restrictions are separate diagnostics. The rules-v1 Health runtime does not refresh retained finding rows, so read each finding’s lastSeenAt before acting on it. Their former point values are not presented as current Health.

​
Health history

GET /platform/bansafe/health/{session}/history returns accepted evaluations for that number. Each point carries the same source, estimator version, coverage, reliability, explanation, and observed-state fields. It does not join retired scores or warm-up send totals into the series.

​
Project Health rules

A project Health rule can act when a fresh, available Health estimate is lower than the chosen threshold. Equality does not trigger it. Available actions are:
  • stop the session while retaining linked credentials;
  • slow sending to a configured rate;
  • log out and require pairing again; and
  • send an email or bansafe.health_threshold webhook. The webhook option requires an enabled project-wide native endpoint subscribed to this event or to all events.
Unknown or stale Health triggers no action. See Safety in Console for configuration and action semantics. GET /platform/bansafe/health-actions?projectId={projectId} returns what each rule action did. It reports the action, public status and outcome, triggering Health and threshold, estimator provenance, and completion time. It does not expose worker leases, retries, runtime identifiers, or free-form internal outcomes.

​
Reporting a ban yourself

If WhatsApp restricts a number and Polymorfa did not observe it, use Report a ban on the Safety page or POST /platform/bansafe/incidents. The report becomes an observed incident; it does not directly set or replace Health. Use a stable Idempotency-Key when retrying the request.

​
Privacy boundary

Polymorfa uses operational counts, timing distributions, connection outcomes, and account-state checks from your own linked session. It does not use message text, media, recipient identifiers, or chat history to estimate Health. Optional device evidence can be unavailable when a report reaches collection limits. Absence of that evidence does not establish which device caused an outcome, so Polymorfa does not infer confident attribution from the absence.

​
Webhooks

bansafe.health_threshold is emitted when a configured project rule queues an action for a fresh Health estimate below its threshold. The payload carries the session and project, Health and threshold, estimator, model, and policy versions, evaluation time, and stable episode and action IDs. Deduplicate retries by the webhook envelope ID, which is the action ID. Provider enforcement, incident, claim, and Polymorfa action events remain separate facts. See Webhooks.