Skip to main content
Pause reason codes are the labels agents attach when they flip themselves to the away state — “Lunch”, “Bio break”, “Coaching”. Devotel Orbit ships a built-in default set, and tenant administrators extend that catalog with domain reasons (hipaa_training, qa_call_review, team_standup) through the dashboard or the API. Each code can carry an optional max-seconds ceiling the platform uses to fire a supervisor overrun alert when an agent stays away past the reason’s budget. This guide covers the whole loop: how pause reasons differ from AUX codes, creating and retiring codes, wiring ceilings, where the catalog surfaces in the agent picker, and what to check when alerts misbehave. Dashboard: Voice → Pause Reason Codes in the sidebar. Base path: /api/v1/voice/agents Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: write scope required for create/update/retire; read scope suffices for listing.

​
1. Pause reason codes vs. AUX codes

Two catalog surfaces live side by side in the dashboard, and they are not interchangeable:
  • Pause reason codes (this page) — the agent away-state taxonomy. An agent picks one when toggling away; the choice lands on the agent-state audit trail and feeds adherence reporting. A per-reason max_seconds ceiling wires the pause-timer overrun alert.
  • AUX codes — the WFM bucket taxonomy supervisors use to aggregate non-ready time for shrinkage and occupancy analytics. One AUX code (“Unpaid break”) can group several pause reasons.
Administer each catalog on its own route: pause reasons under Voice → Pause Reason Codes, AUX buckets under Voice → AUX Codes. The built-in default pause reasons are lunch, bio, training, break, and coaching; the defaults ship with platform ceilings (see section 3) and cannot be redefined.

​
2. Create a pause reason

A new reason goes live for every picker the moment it saves.
cURL
Body fields:
  • code — machine slug, lowercase letters/digits/_/- only (max 64). Agents send this value, so keep it stable.
  • display_label — the human label the picker renders (max 64).
  • max_seconds — optional integer ceiling, 1–86400. Omit or send null when a supervisor should nudge agents manually.
  • active — defaults true; create with active: false when you want to stage a code before rollout.
Create returns 201 with the stored row. Two rejection classes exist at create time:
  • 422 with reason: "SHADOWS_DEFAULT" — the code collides with a built-in default. Operators extend the catalog; they never silently override a default.
  • 409 with reason: "DUPLICATE_CODE" — another row with the same (organization, code) already exists. Retire the old row first, or pick a different slug.

​
3. Set the max_seconds ceiling — and what it emits

Every away-state entry is time-checked against the ceiling its reason carries. The platform ships default ceilings for the built-in codes: bio 8 minutes, break 15, lunch 45, training 4 hours, coaching 1 hour. Tenant-defined reasons start uncapped (null), and you assign a ceiling at create or via a later update. When an agent’s open away-state exceeds max_seconds for the chosen reason, the platform:
  1. Publishes a state_reason.overrun event on the tenant’s live event bus — the supervisor wallboard and any SSE subscriber listening on the state_reason.overrun event type sees a per-agent banner naming the agent and the elapsed budget.
  2. Optionally flips the agent back to available when your organization setting settings.ccaas.auto_available_on_overrun is true. The default is alert-only — most floors want a supervisor to nudge the agent first; the auto-flip setting lives under Settings → Voice controls.
Rules worth knowing before you set ceilings:
  • Uncapped reasons never alert. A reason with max_seconds: null is deliberately silent.
  • Strictly-past-the-ceiling semantics. An agent at exactly the boundary does not trip the alert; the scan runs on a roughly one-minute cadence, so expect the first event within a minute of crossing.
  • Suppress repeat noise. Per-agent dedupe holds the alert at one event while the breach persists, so a forgotten break does not flood the wallboard.
  • Setting auto_available_on_overrun closes the open entry cleanly, so the next shift-adherence report does not double-count the overrun as in-policy away time.

​
4. Edit, archive, and unarchive

PATCH /api/v1/voice/agents/pause-reason-codes/{id} accepts any subset of display_label, max_seconds, and active, and refuses an empty patch.
  • Rename the label — PATCH -d '{"display_label":"Team standup"}' — future picks render the new label immediately.
  • Adjust or clear the ceiling — send max_seconds: 1800 to tighten, or max_seconds: null to remove the ceiling entirely. The distinction matters: omitting the key preserves the current value.
  • Archive — DELETE /api/v1/voice/agents/pause-reason-codes/{id} flips active to false. This is a soft delete: the code leaves every picker, but historical agent-state history still dereferences it to a label.
  • Unarchive — PATCH {"active":true} restores the code to pickers.
code is immutable — every historical away-state entry records the slug, and renaming it would orphan that audit data. If you need a renamed slug, retire the old row and create a new one.
cURL
List the whole catalog, including retired rows, with ?include_inactive=true:
cURL
The list response also echoes the built-in defaults array so the admin surface can render defaults alongside tenant rows and flag shadowing attempts before you submit.

​
5. Where pause reasons appear in the agent picker

An agent flips themselves away from the softphone status toggle; the away-entry picker renders the union of the built-in defaults plus every active tenant row, sorted by code. GET /api/v1/voice/agents/state-reasons merges the two, so any custom away picker you build should read that endpoint rather than the admin list — the admin list only returns the tenant-defined rows. Each picker’s entry carries the reason’s display_label and, when set, its max_seconds so the agent UI can render how long the budget allows before overrun. An archived reason disappears on the next picker refresh; an unarchived one reappears identically.

​
6. Troubleshooting

  • Agents report an overrun alert but no ceiling is set: the reason may shadow a built-in default on a duplicate route, or the org had auto_available_on_overrun enabled previously and the flip-back left the old event closed — the alert fires only while a ceiling exists. Run the include-inactive list and inspect the row’s live max_seconds.
  • No overrun event reaches the dashboard: confirm the wallboard subscribes to the state_reason.overrun SSE event type, and that the offending agent’s open away entry has actually crossed the reason’s ceiling — the scheduler skips unknown or uncapped codes silently. A ceiling set to null at creation means “never alert.”
  • 422 with SHADOWS_DEFAULT on create: the slug collides with a built-in default (lunch, bio, training, break, coaching). Pick a distinct slug; built-ins are never redefined.
  • A new reason does not appear in the picker: verify active was not staged to false at create, and that agents refreshed the after-call toggle — the picker re-reads the catalog on every away-state open.
  • Archived code still selected by a stuck legacy softphone: an in-flight away-state set before the archive remains valid until the agent re-picks. The catalog blocks the next pick; there is no retroactive rewrite of the in-shift choice.

​
See also