Agent wellness and flight risk

Contact centers lose agents to burnout long before anyone files a resignation. The distress button — the one-tap panic control on the softphone — catches the acute moment an agent asks for help mid-call, but it is agent-initiated and binary: an agent sliding toward attrition over weeks rarely presses it. The wellness surface closes that gap by computing a per-agent strain score from data Orbit already captures, and the flight-risk surface takes the same idea one step further by tracking whether those signals are trending worse. This guide is for supervisors and WFM managers. It walks the two lenses, the role gate that decides who sees what, the five strain inputs behind each score, every endpoint parameter, the band thresholds, and a supervisor runbook for acting on a nudge without turning a wellbeing signal into a performance flag. The full endpoint shapes live on the WFM API page — this guide is the narrative for the wellness and attrition half of that reference. Neither surface stores anything. Both are derived, on-the-fly readings over tables your tenant already populates — call records, adherence events, shrinkage reports, distress alerts. There are no new biometric feeds, and nothing is captured about an agent that the platform was not already recording for operations.

1. The two lenses — wellness vs the distress button

The agent distress alert model defines the reactive lens: one press of the panic button persists a supervisor alert, forces the call into a recorded state, and pages the supervisor. It is instant, acute, and agent-initiated. Its role is safety in the live moment, not trendspotting. The wellness lens is the passive counterpart. GET /api/v1/wfm/agent-wellness re-aggregates data Orbit already records — call load, after-call-work overrun, occupancy, adherence pressure, and any raised distress events — and runs the aggregate through a scoring kernel that returns a wellness score per agent. A supervisor reads a grid where the most strained agents sort to the top, with a recommendation keyed to the top driver: suggest a break, lighten routing, review the schedule, or check in one-on-one. The flight risk lens widens the time horizon. GET /api/v1/wfm/agent-flight-risk splits a longer window into two halves — recent vs prior — and weights how much worse the recent half looks, because a worsening trajectory is the actual leading indicator of attrition. A busy agent who is flat is not a flight risk; an agent whose adherence, shrinkage, and break-state time are all climbing is. Two rules hold across both lenses:

Wellness is non-punitive by design. The score drives workload relief — breaks, lighter routing, a schedule-fit conversation — never discipline. The recommendation copy the API returns is written to be read aloud to the agent.
Distress events feed both surfaces. A single distress-button press in the window already contributes meaningful strain to wellness and risk to flight-risk, so the passive read never ignores the reactive one.

2. Role gate — who sees what

Both endpoints admit owner, admin, and supervisor roles. Wellness also admits the per-agent (developer / viewer) seats, and the role gate is what separates them:

Caller role	Wellness grid	Flight-risk grid
`owner`, `admin`, `supervisor`	Every agent	Every agent
Agent seat (`developer`, `viewer`, or any other role)	Their own row only	Empty grid

The asymmetry is deliberate. An agent seeing their own wellness score is a self-care signal — they can ask for a break before the supervisor notices. Attrition risk, by contrast, is a manager-retention conversation: letting an agent see their own “likely to leave” number would poison the very check-in the playbook recommends, so flight-risk returns nothing to restricted roles. A restricted caller whose identity cannot be resolved gets an empty wellness result too — the gate fails closed.

3. The five wellness inputs

Every wellness score decomposes into five strain signals, each normalised to 0–100 where higher means more strain. The weighted blend inverts to a 0–100 wellness score where higher is healthier. The five inputs:

Call load — answered calls, total talk time, and back-to-back density (answered calls separated by less than short_recovery_gap_seconds) in the window. Blended as 50% volume, 30% talk-time, 20% back-to-back share against the per-day baselines.
ACW overrun — the share of wrap_up adherence events whose duration exceeded acw_ceiling_seconds. Sustained overrun points at tooling or escalation blockers, not at a slow agent.
Occupancy — occupied time (on_call + wrap_up) over signed-on time, accruing strain only above occupancy_healthy_ceiling (default 0.85). Occupancy below the ceiling contributes zero strain — a busy-but-recovering agent is not flagged.
Adherence pressure — the share of evaluated adherence events marked non-adherent. This is treated as a workload-fit signal, never a performance flag.
Distress — distress-button events raised in the window. High-signal, low-frequency: a single press lands at 50 strain and saturates by the third.

Flight risk uses a different five — shrinkage (mean unscheduled-absence ratio), adherence breaches, aux escape (signed-on time in unavailable/break/lunch states), burnout (occupancy above the healthy floor, or any distress event), and trend (recent half vs prior half of the first three). Only worsening deltas accrue trend risk — a flat or improving trajectory contributes zero.

4. The wellness endpoint in full

curl "https://api.orbit.devotel.io/api/v1/wfm/agent-wellness?window_days=7" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Query parameters, all optional:

Parameter	Default	Bounds	Effect
`window_days`	7	1–30	Rolling window the counters are aggregated over.
`acw_ceiling_seconds`	120	1–3600	Wrap-up duration above which an event counts as ACW overrun.
`short_recovery_gap_seconds`	15	0–600	Gap below which two consecutive answered calls count as back-to-back.
`nudge_threshold`	55	0–100	Wellness score below which the `needs_nudge` flag and recommendation fire.
`occupancy_healthy_ceiling`	0.85	0–1	Occupancy ratio above which strain starts accruing.
`calls_per_day_baseline`	40	1–1000	”Full but healthy” answered calls per day for the call-load ratio.
`talk_hours_per_day_baseline`	5	0.5–24	”Full but healthy” talk hours per day.
`weight_call_load`	0.25	0–1	Blend weight for call-load strain.
`weight_acw_overrun`	0.2	0–1	Blend weight for ACW overrun strain.
`weight_occupancy`	0.2	0–1	Blend weight for occupancy strain.
`weight_adherence_pressure`	0.15	0–1	Blend weight for adherence-pressure strain.
`weight_distress`	0.2	0–1	Blend weight for distress strain.
`limit`	100	1–500	Page size — one row per active agent.
`cursor`	—	—	Opaque page token; pass the previous response’s `next_cursor`.

Weights re-normalise internally, so passing one weight alone re-balances that signal against the others without you re-supplying all five. The response envelope carries rows (one per agent: identity, raw counters, and the score block), counts (agents per band plus needs_nudge), config (the resolved coefficients — pass it back to reproduce the same math), window (days, since, pagination state), next_cursor, and generated_at. Rows sort worst-first, so the supervisor’s triage list is the top of the first page. A fuller wellness read over a 7-day window, tuned to a queue where 90 seconds of wrap-up is the norm and occupancy past 80% hurts:

curl "https://api.orbit.devotel.io/api/v1/wfm/agent-wellness?window_days=7&acw_ceiling_seconds=90&occupancy_healthy_ceiling=0.8&nudge_threshold=60&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Each row in rows carries:

{
  "agent_id": "user_agent_12",
  "display_name": "Amira Okafor",
  "wellness_score": 48,
  "strain_score": 52,
  "band": "elevated",
  "needs_nudge": true,
  "signals": {
    "call_load": 61.2,
    "acw_overrun": 44.0,
    "occupancy": 38.5,
    "adherence_pressure": 12.0,
    "distress": 0
  },
  "drivers": [
    { "signal": "call_load", "strain": 61.2, "weight": 0.25, "contribution": 15.3 }
  ],
  "recommendation": {
    "action": "suggest_break",
    "message": "Sustained back-to-back call load — suggest a smart break and steer new contacts to other agents."
  },
  "occupancy_ratio": 0.88
}

drivers is the per-signal breakdown sorted by contribution — that is the supervisor’s answer to “why is this agent flagged.” inputs echoes the raw counters behind the signals when you want to sanity-check a score.

5. Band thresholds and the `nudge_threshold`

The wellness score lands in one of four bands:

Band	Wellness score	Reading
`healthy`	70–100	No strain pattern — leave the agent alone.
`monitor`	50–69	Mild strain; watch the trend, no intervention.
`elevated`	30–49	Strain is real; a supportive action is worth it.
`at_risk`	0–29	Sustained strain; act this week, not this quarter.

The nudge_threshold sits on top of the bands and decides which rows carry needs_nudge: true plus a recommendation. The default of 55 means the bottom of the monitor band and anything worse nudges; raising it to 60 tightens the trigger to only reliably-strained agents, lowering it to 40 makes the nudge rare. The shared example below runs the same roster with the shared example value nudge_threshold=60:

curl "https://api.orbit.devotel.io/api/v1/wfm/agent-wellness?window_days=7&nudge_threshold=60" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Because the band boundaries are fixed (70 / 50 / 30) and the nudge threshold is a per-request knob, you can compare thresholds across supervisors by simply re-calling with a different value — the scoring math is deterministic, and config in the response tells you exactly which coefficients produced it. The flight-risk sibling uses its own bands — low (0–29), watch (30–49), elevated (50–69), high (70–100) on the flight-risk score — with alert_threshold (default 60) gating needs_alert, plus one wellness has no analogue of: a data-sufficiency floor. min_observations (default 20 evaluated adherence events) marks rows reliable: false when the window is too thin, and no alert fires on thin data — false alarms are how attrition models lose supervisor trust.

6. Flight-risk pairing

Wellness tells you who is struggling now; flight risk tells you who is slipping over time. Run them together — wellness for the daily stand-up, flight risk weekly as the leading indicator:

curl "https://api.orbit.devotel.io/api/v1/wfm/agent-flight-risk?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Query parameters, all optional:

Parameter	Default	Bounds	Effect
`window_days`	30	14–90	Window split into recent vs prior halves. Attrition is slow-burn; under 14 days the halves are meaningless.
`alert_threshold`	60	0–100	Flight-risk score at or above which `needs_alert` fires.
`min_observations`	20	0+	Evaluated events below which the row is unreliable and never alerts.
`shrinkage_ceiling`	0.35	0.01–1	Mean shrinkage ratio at which shrinkage risk saturates.
`adherence_breach_ceiling`	0.3	0.01–1	Breach share at which adherence risk saturates.
`aux_escape_ceiling`	0.4	0.01–1	Aux-state share at which aux-escape risk saturates.
`occupancy_burnout_floor`	0.85	0–1	Occupancy above which burnout risk starts accruing.
`weight_shrinkage` / `weight_adherence` / `weight_aux_escape` / `weight_burnout` / `weight_trend`	0.25 / 0.2 / 0.2 / 0.15 / 0.2	0–1	Blend weights; re-normalised internally.
`limit` / `cursor`	100 / —	same as wellness	Pagination.

Each row adds trajectory_delta — the signed composite of recent-vs-prior deltas, −100 to 100. Negative is improving, positive is worsening, and zero means flat. The playbook acknowledges improvement too: a reliably low-risk agent at trajectory_delta <= -10 gets a recognition prompt, because retention is reinforced as much by catching good trajectories as by catching bad ones. A 30-day pass alongside the wellness read:

curl "https://api.orbit.devotel.io/api/v1/wfm/agent-flight-risk?window_days=30&alert_threshold=55&min_observations=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Interpreting the pairing: an agent at_risk on wellness but low on flight risk is having a bad week — fix the workload, not the retention plan. An agent monitor on wellness but high on flight risk is the expensive case the wellness lens alone misses — the trajectory says the wheel is coming off even if this week looks survivable. Elevated on both is the same finding confirmed twice.

7. Supervisor runbook — what a nudge means

A needs_nudge row is an instruction to the supervisor to relieve workload, and the recommendation.action narrows the instruction:

suggest_break — top driver is call load or occupancy: route new contacts elsewhere and get the agent a real break. Today, not at the next schedule cycle.
lighter_routing — ACW overrun is high: check for an escalation blocker or a tooling issue first. Wrap-up overrun means the work after the call is not finishing; it is rarely the agent’s fault.
review_schedule — adherence pressure: look at schedule fit. Adherence breaches drifting up across a whole week are a roster mismatch signal, and the recommendation copy says so.
check_in — distress events in the window or flight-risk trend worsening: a supportive one-on-one. Not a performance conversation.
none — wellness in a healthy range.

On the flight risk side, playbook.action carries the same intent with longer-horizon moves — schedule_relief, coaching, workload_rebalance, check_in, or recognition for the low-risk improver. The framing matters and the API enforces it: messages are written to be read aloud to the agent. Treating wellness scores as a performance ranking is the fastest way to make agents never press the distress button, which destroys the one high-signal input both models depend on. A supervisor who acts on a nudge by relieving the workload makes the next nudge trustworthy; one who acts on it with a write-up makes the whole surface dishonest.

8. Production checklist

Before you rely on either surface operationally, walk this once:

Privacy posture stated to the team. Wellness and flight risk read data the platform already records for operations — adherence events, call records, distress alerts — and compute on the fly with nothing persisted. Agents can see their own wellness score; flight risk is manager-only by design. State both facts in your team handbook before a supervisor reads any score aloud.
Non-punitive framing reviewed. The recommendation and playbook copy are deliberately supportive. If your internal scorecards discuss these numbers, the wording should match the API’s — workload relief, schedule fit, coaching, recognition.
Role gates audited. Confirm owner/admin/supervisor intake is deliberate on your tenant — these roles see every agent. Agents (developer/viewer seats) see only their own wellness row and nothing on flight risk; a restricted caller with no resolved identity fails closed.
Baselines tuned once. The defaults (40 calls/day, 5 talk hours/day, 85% occupancy ceiling) are a starting point. Tune calls_per_day_baseline, talk_hours_per_day_baseline, and occupancy_healthy_ceiling to your queue’s reality, then pass the same values on every call — config in the response is your record of what you tuned to.
Thin-data discipline on flight risk. Never act on a reliable: false row, and never lower min_observations into single digits. An attrition alert with twelve evaluated events behind it is noise with a name attached.
Adherence feed healthy. Both surfaces lean on adherence events for occupancy and adherence-pressure signals. If agents do not set their aux state in the dialer or inbox, occupancy reads near zero and adherence pressure reads blank — fix the feed before drawing conclusions, the same prerequisite the WFM workflows guide calls out for scheduling.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Agent wellness and flight risk

Agent wellness and flight risk

1. The two lenses — wellness vs the distress button

2. Role gate — who sees what

3. The five wellness inputs

4. The wellness endpoint in full

5. Band thresholds and the `nudge_threshold`

6. Flight-risk pairing

7. Supervisor runbook — what a nudge means

8. Production checklist

See also

​Agent wellness and flight risk

​1. The two lenses — wellness vs the distress button

​2. Role gate — who sees what

​3. The five wellness inputs

​4. The wellness endpoint in full

​5. Band thresholds and the nudge_threshold

​6. Flight-risk pairing

​7. Supervisor runbook — what a nudge means

​8. Production checklist

​See also

Agent wellness and flight risk

1. The two lenses — wellness vs the distress button

2. Role gate — who sees what

3. The five wellness inputs

4. The wellness endpoint in full

5. Band thresholds and the `nudge_threshold`

6. Flight-risk pairing

7. Supervisor runbook — what a nudge means

8. Production checklist

See also