Skip to main content

​
Call Disposition Tags

A disposition tag is a label you stamp on a call: lead, vip, escalated, follow-up. Unlike a queue’s wrap-up code, which records a single outcome from a catalog defined per queue, disposition tags are a tenant-wide, many-per-call labeling system you curate from the dashboard. Use them to slice voice analytics and build segments across queues and campaigns. This page covers the tenant-level tag catalog and stamping. If you are looking for the per-queue wrap-up catalog that gates busy → available (set requireDisposition on the queue; those codes come from queue configuration, not this editor), see Wrap-up codes. Base path: /api/v1/voice Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: voice read to list the catalog and read a call’s stamps, voice write to stamp a call. Catalog create, update, and delete are restricted to owners and admins.

​
The tenant-level catalog, and how it differs from wrap-up codes

Orbit keeps two separate disposition axes. They sound alike and are easy to conflate: Each tag row has:
  • slug: the lowercase identifier you post back (for example lead, vip, escalated, follow-up). Unlike a wrap-up code, the slug is mutable: stamps reference the catalog row by id, so renaming a tag rewrites history cleanly instead of orphaning past stamps.
  • label: the human-readable text the picker and chips show.
  • color: optional hex value for the chip swatch.
  • sortOrder: picker display order.
  • isActive: retiring a tag is a soft-delete. Historical stamps keep resolving the label, the slug is freed for reuse, and you can reactivate the row later.
A slug must be unique among the tenant’s active tags. Creating or renaming into a duplicate returns 409 DISPOSITION_TAG_ALREADY_EXISTS.

​
Curate the catalog in the dashboard

Open Voice → Disposition Tags. Owners and admins can:
  1. Create a tag with a slug, label, and colour.
  2. Rename a tag (slug or label). Past stamps follow the rename because they reference the row, not the slug.
  3. Recolour the chip swatch, or reorder the picker.
  4. Retire a tag. This is a soft-delete: stamps keep the label and the slug becomes available again. Reactivate from the same editor with the inactive-rows view.
Agents stamp from the catalog but do not curate it.

​
Stamp and read tags on a call

On a call’s detail page, the disposition-tag panel shows the tags already applied as coloured chips and offers the remaining active catalog for stamping. Applying is additive: re-stamping the same tag on the same call is idempotent (a retry refreshes who stamped it and when instead of duplicating the row), and there is no un-stamp operation (catalog retirement, not deletion from a call, is how a label leaves circulation). Typical starter catalog: lead, vip, escalated, follow-up, plus your own product or campaign labels (for example product-bug-login).

​
REST equivalent

Stamp a call by slug, or by catalog id; you can mix both in one request:
A slug or id that does not resolve to an active catalog row returns 404 DISPOSITION_TAG_NOT_FOUND with the missing values listed. The stamp records the principal who posted it, so audit and analytics attribute the label correctly. queueId is optional context for where the stamp originated. Read a call’s current stamps:
The response joins against the catalog, so chips still render a label and colour even for a tag retired after the stamp.

​
Catalog REST endpoints

For automation, such as syncing a taxonomy from another system or bulk-curating tags: Create body: slug, label, optional color (hex), optional sortOrder. Update accepts any subset of those fields plus isActive; a rename that lands on another active tag’s slug returns 409.

​
Audit and analytics posture

Every catalog change and every stamp lands in the audit log with the actor (voice.disposition_tag.created/updated/deleted, voice.call_tag.stamped), so QA can answer “who labeled this call and when.” Tags exist purely in Orbit’s data plane. Stamping a tag never touches SIP signalling; it changes no call routing, no billing, and no provider interaction. Tags stamp analytics: use them to filter and segment voice reporting (for example, compare handle time for vip-stamped calls against the fleet), alongside the outcome axis that wrap-up codes record.