Skip to main content
An AUX code (short for “auxiliary”, the telephony term for a not-ready reason) is a presence reason an agent picks when they step away from taking calls: lunch, break, training, coffee, meeting, whatever your floor actually uses. The editor at Voice → AUX Codes is the per-tenant catalog of those reasons. Agents see the labels when they change their status; workforce-management reporting buckets each one downstream. Every control on this page is tenant-owned: the catalog, the bucket mapping, the paid flag, and the ordering live in your organization’s configuration. Creating or editing a code changes reporting configuration only — it never touches call routing.

​
1. Why AUX codes matter: adherence buckets and paid vs unpaid

Each AUX code carries two properties that decide how it counts in adherence reporting:
  • Adherence bucket — one of the fixed WFM vocabulary: available, on_call, wrap_up, break, lunch, training, unavailable, or logged_out. Every minute an agent spends in the code rolls into that bucket. Extend the vocabulary freely on slugs (coffee, 1-on-1, dental); the bucket tells the report how to classify it.
  • Paid flag — whether time in the code counts as paid. Paid breaks and unpaid lunch are the common split; your payroll export can read the flag directly.
Out of the box the platform understands three default reasons (lunch, break, training) and falls back to unavailable for anything else. The catalog overrides that: when you add a code, its explicit bucket replaces the fallback for every agent who picks it. Codes you don’t add fall back to the defaults, unchanged.

​
2. Open Voice → AUX Codes and create a code

In the dashboard, open Voice → AUX Codes. The page lists your active catalog ordered by the sort position you set. To add a code, click Create code and fill in:
  • Code — the slug agents’ status changes record. Lowercase ASCII letters, digits, hyphen, underscore; 1–64 characters. The slug is immutable once created (see archiving below).
  • Label — the human-readable name shown in the agent picker, up to 200 characters.
  • Adherence bucket — one of the eight fixed buckets above.
  • Paid — on for paid time, off for unpaid.
  • Sort order — integer 0–10,000 (default 100). Lower numbers float higher in the picker.
The Voice → AUX Codes editor listing the active catalog Create via the API:
cURL
A slug collision against an active code returns 409 AUX_CODE_ALREADY_EXISTS. A slug colliding only against an archived code creates fine — the active set is what is unique.

​
3. Edit, archive, and restore the catalog

Creating a new AUX code — slug, label, bucket, paid flag, and sort order Any member with the owner or admin role can edit; agents and supervisors pick from the catalog but a 403 tells them they can’t change it.
  • Edit — the label, bucket, paid flag, sort position, and active flag are all mutable. The slug is not: it is the identifier stored verbatim on the audit trail, so renaming would orphan historical rows. To rename, archive the old slug and create the new one.
  • Archive — a soft delete. The code disappears from the agent picker and every new status change; history keeps the recorded slug.
  • Restore — flip isActive back to true from the archived list (includeInactive=true), and the code is live again.
Editing or archiving an AUX code — archive is a confirmed soft delete List via the API (defaults to active only, paginated):
cURL
Update or archive / restore:
cURL

​
4. How agents pick a code when changing presence

When an agent’s status changes in the dialer or inbox — stepping away, finishing a call, returning to available — the picker lists every active AUX code ordered by sort position, and the recorded slug lands on their status-change event. An agent with no code to pick still flips between the built-in defaults (lunch, break, training, or unavailable fallback). The catalog only extends the options; it never leaves agents without one.

​
5. How codes feed adherence reporting

Adherence compares schedule-versus-actual: the minutes an agent spends in each presence state roll into the bucket its code maps to, and the paid flag decides whether the minutes count toward payroll. The bucketing is what makes reports readable — 40 slugs would be noise; eight buckets are a plan. Related reading:

​
6. Troubleshooting

A code is missing from the agent picker. Archived codes never render. List with includeInactive=true to check; restore via PATCH { "isActive": true }. A new code returns 409. The slug collides with an active row. Pick a different slug — or archive the collision first and re-create to “rename.” Agents see a 403 editing the catalog. Only owner and admin can create, update, or delete; agents and supervisors pick from the list. Issue an API key with the right role, or use a dashboard session with one of those memberships. Sort order not applying. Sort position is an integer 0–10,000 and applies to the active set rendered in the picker; archived rows sort to the bottom regardless. Audit trail. Every create / update / archive / restore writes to the audit log with actor, timestamp, and the slug. Read the audit log guide to query the trail (voice.aux_code.created, voice.aux_code.updated, voice.aux_code.deleted).