> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage pause reason codes

> Extend the agent away-state (pause) reason catalog with your own codes, set per-reason max-seconds ceilings that drive overrun alerts, and retire or restore codes — tenant-administered, no deploy required.

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.

```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "hipaa_training",
    "display_label": "HIPAA training",
    "max_seconds": 3600
  }'
```

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.

```bash cURL theme={null}
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes/pauseReasonCode_01HZ..." \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "display_label": "HIPAA training (monthly)", "max_seconds": 7200 }'
```

List the whole catalog, including retired rows, with `?include_inactive=true`:

```bash cURL theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes?include_inactive=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

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

* [Voice queues](/guides/voice-queues) — the ACD surface that consumes agent availability
* [Wallboard alarm rules](/guides/wallboard-alarm-rules) — the supervisor alert surface that renders overrun banners
* [Workforce-management workflows](/guides/wfm-workflows) — adherence exceptions and shift analytics on top of away-state history
* [Voice API reference](/api-reference/endpoints/voice) — parameter and response detail for the pause-reason endpoints