Skip to main content

​
Agent presence and aux-code lifecycle

An agent’s presence is the one fact every routing decision checks first. Voice dispatch looks at it before ringing, the omnichannel capacity ledger folds it into the digital load, and supervisor wallboards tile agents by it. This page defines the five-state machine those readers share, who moves each edge, and how it degrades when the persistence layer blips. It pairs with Hold and pause reason codes, which covers the code catalogs themselves, and the Attendant console, which covers the live supervisor view.

​
The five states

Presence lives on each queue membership — an agent holds one state per queue, and every reader (dispatch, capacity, wallboard) folds the memberships into a single worst-case state by severity: busy > wrapup > paused > offline > available. The persistence CHECK constraint allows exactly these five values — the softphone toggle writes a four-value shorthand (available | busy | away | offline) and the API maps away → paused at the storage boundary, so the audit table always carries the full five-state vocabulary.

​
Who moves each edge

Every accepted toggle appends a row to the state-history audit with the old state, new state, and (for paused) the reason code — supervisors and WFM adherence read live state from the open event row, and reporting reads the closed history.

​
Aux / pause reason codes

The platform ships five defaults — lunch, bio, training, break, coaching — and owners or admins extend the catalog per tenant: Codes are lowercase slugs matching ^[a-z0-9_-]+$, up to 64 characters, with an optional max_seconds ceiling (1–86400). Setting a ceiling gives the overrun check something to fire on: when an agent sits in paused past the code’s ceiling, a state_reason.overrun alert raises, and tenants that enable auto-available-on-overrun flip the agent back to available automatically. Codes with no ceiling alert manually — the supervisor nudges, the platform never assumes a duration it has not been given. For WFM reporting, lunch, break, and training are first-class adherence states; other codes roll into the generic unavailable bucket. paused only gates voice. A digital-channel claim (chat, email, tickets) never checks it — the lobby excludes paused agents from the voice eligible list, and that is all the pause does to routing.

​
Wrap-up window (ACW)

When a call ends, dispatch flags the membership wrapup and starts the queue’s wrap-up timer. While it runs:
  • The agent is excluded from the voice eligible list — no queue ring finds them.
  • The window ends either when the scheduler’s expiry fires (per queue, with a platform maximum on the queue’s wrap-up setting) or when the agent posts a disposition early — a callback writeback also clears the state immediately so a taken callback does not idle behind the timer.
If an agent never submits and the timer expires while the queue is still dispatching, the membership flips back to available and the wallboard’s wrap-up counter decrements. Design queue wrap-up durations to cover the longest disposition form your agents actually fill — the firing is a straight elapsed > limit check with no grace window.

​
How dispatch consults presence

Two readers consume the same state, with different scopes:
  • Voice ACD. When a call enters a queue, the eligible list is the members whose worst-case membership state is available. Ring order, skills, and offers are moot for a membership that is not eligible — so membership flips are never half-applied.
  • Omnichannel capacity. For blended agents the capacity ledger gives each state a numeric voice bracket — available scores its full bracket, busy and wrapup score near zero, paused and offline score zero — and adds it to the digital conversation load to compute one saturation number per agent. The supervisor wallboard and the digital router sort on that number when deciding who should get the next conversation. Only available agents are dispatch candidates for either channel; the numeric bracket just orders them.
Both readers treat offline as empty-set — a logged-out agent disappears from the claim pool entirely, and the idle-logout sweep enforces that rather than leaving phantom-available rows.

​
Where agents and supervisors read and write state

  • Softphone (agent): the status toggle and the aux/pause picker. The toggle accepts available | busy | away | offline; away requires a reason code that must resolve against the defaults plus your tenant’s active catalog, otherwise you get a 422.
  • Attendant console (supervisor): the live grid, staffed by the open-event reader, plus state-filter chips and per-agent drill-down. Full details in Attendant console.
  • State history: every accepted transition lands in the audit log with the reason code when paused; supervisors use it for adherence, and the soft-delete semantics of the reason catalog keep retired codes readable in that history for as long as the rows exist.

​
Failure postures

Live routing treats the in-memory agent registry as the source of truth; the persistence write-through that mirrors states to the audit tables is best-effort. Concretely:
  • When the audit write fails, the transition still happened — dispatch keeps working on the live registry and the missed history row just shows a gap in adherence reporting. The write failure is logged and counted, not raised to the client.
  • When the queue’s pause-catalog read hits a blip, the picker degrades to the platform defaults and the validator accepts the defaults-only set — no toggle is blocked for a tenant whose extension catalog is temporarily unreadable.
  • When applying a softphone toggle and the catalog is down, an unknown code against a degraded catalog still 422s — agents never invent a slug by mistake.
Both directions keep the same rule: reading a degraded view returns fewer options, writing with partial data never silently invents options.

​
Owning your taxonomy

The default five codes are a starting vocabulary, not a mandate. Add tenant codes for the reasons your operation actually reports on (hipaa_training, qa_review, team_standup), give each a label agents read, and set a ceiling when you want overrun alerts. Codes stay tenant-owned and tenant-visible end to end — nothing here routes through platform-global gates, and the eligibility rules on this page are the same deterministic state checks dispatch runs, not predictive scoring.