Skip to main content
Disposition tags are the outcome labels agents stamp on a call — “Sale made”, “Callback scheduled”, “No answer”, “VIP”. Each call can carry several tags at once, which makes them different from the single wrap-up code a queue requires. Devotel Orbit ships the tag catalog empty so your taxonomy stays yours, and supervisors curate it through the dashboard or the API. This guide covers the whole loop: how tags differ from wrap-up codes and pause reasons, designing the catalog, where agents stamp them, reading tag-based reporting, QA uses, and the hygiene rules that keep the catalog usable. Dashboard: Voice → Disposition Tags in the sidebar. Base path: /api/v1/voice/disposition-tags Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: admin write scope required for catalog CRUD; agents stamp tags with voice write scope.

​
1. What a disposition tag is — and what it is not

Three labeling surfaces sit next to each other in voice operations, and they answer different questions:
  • Disposition tags (this page) — the per-call outcome taxonomy. A call can carry many tags (sale-made + callback + vip), so reports can answer “what happened on these calls?” across several overlapping categories at once. Tags are tenant-wide: every team shares one catalog.
  • Wrap-up disposition codes — the per-queue required-code taxonomy. A queue with require_disposition enabled blocks an agent’s busy → available flip until exactly one code is recorded. That axis gates agent availability; tags never do.
  • Pause reason codes — the agent away-state taxonomy (“Lunch”, “Coaching”), documented in Manage pause reason codes. Those label agent time, not call outcomes.
Pick the tag axis when the same call legitimately falls into several buckets and you want all of them searchable. Pick the wrap-up-code axis when a queue enforces “no availability until a disposition exists.”

​
2. Design the tag taxonomy

Create tags in Voice → Disposition Tags, with slug + label + optional color + sortOrder. Some starter sets by team type:
  • Outbound sales floor: sale-made, sale-lost, callback, wrong-number, decision-maker-absent, no-answer.
  • Inbound support: resolved, escalated, refund-requested, product-bug, follow-up.
  • Collections: promise-to-pay, dispute, wrong-party, refused-payment.
  • Cross-cutting flags (any floor): vip, churn-risk, lead, complaint.
A new tag goes live in every picker the moment it saves.
cURL
Body fields:
  • slug — machine slug, lowercase letters/digits/_/- only (max 60). Stamping clients can send slugs directly, so keep them stable.
  • label — the human label pickers render (max 200).
  • color — optional chip color, hex or token slug (max 32).
  • sortOrder — optional integer, default 100; lower sorts first in the picker.
Create returns 201 with the stored row. A 409 with code DISPOSITION_TAG_ALREADY_EXISTS means another active row already owns the slug — retire the old row or pick a different slug.

​
3. Where agents stamp tags

Agents pick tags from two surfaces; both resolve against the live tenant catalog:
  • Softphone / call-detail page — the per-call chip editor on Voice → Calls → [call] shows the tenant’s active tags as toggle chips and applies them in one batch. Read and stamp both happen here, so an agent can also see what a colleague stamped.
  • After-call wrap — a tag pick is usually part of the wrap-up block, and the stamp endpoint accepts them together with the queue the call arrived on.
cURL
Stamping accepts tagSlugs (operator-friendly) or tagIds (pre-resolved catalog UUIDs), or both; the server dedups by resolved tag. A stamp is idempotent on the call-tag pair — re-applying a tag refreshes who stamped it and when, without duplicating the audit row. A batch of 1–64 tags lands in a single round-trip. Read the current assignments on a call with:
cURL
The read joins back against the catalog so labels still resolve even after a tag is retired (assignment history keeps the label snapshot).

​
4. Read tag-based reporting

Tags feed the analytics surfaces through the same catalog + assignment tables the stamp endpoint writes:
  • Tag coverage in Insights — supervisors open Voice → Calls and filter by one or more tags to see the share of calls each tag accounts for, so coverage drift (a tag agents stopped applying) is visible before the downstream report goes stale.
  • Cross-cutting segments — because tags are many-to-many, a supervisor can cross-segment “all churn-risk calls that were also escalated” rather than picking a single primary outcome.
  • Per-agent tagging adherence — the stamped rows carry assigned_by, so a weekly supervisor review can flag agents whose calls consistently lack any outcome tag (see section 6 on preventing this).
The envelope is paginated (page / pageSize, plus total) on both the catalog list and the per-call assignment list, so report UIs can page large catalogs without a full-table read.

​
5. QA and coaching uses

Tag filtering is the fastest way to build a coaching cohort without listening to everything:
  • Filter recordings by disposition — QA reviewers open Voice → Calls, select no-answer or escalated, and jump straight to the call recordings that matter this week instead of a random sample. The recordings view links through from the call row. See Recording view analytics for the playback-side detail view.
  • Coaching cohorts — supervisors set up a saved filter like product-bug + escalated and treat the tag intersection as the coaching queue.
  • Spot-checks on sensitive outcomes — refund-requested or complaint tags define a targeted review sample that is reproducible week to week.
Tags are also the input the QA sampling surface can weight against, so high-stakes outcome categories can claim a larger fraction of sampled minutes.

​
6. Tag hygiene rules

The catalog is a supervisor-owned taxonomy, and it stays useful only inside a few rules:
  • Cap the active set. Ten to thirty tags is a working ceiling — past that, agents stop picking reliably and every report starts measuring hesitation rather than outcome.
  • Never accept free-form values. Picker chips beat text input: free-form means Sale, sale, and sold become three different tags in week two.
  • Prefer retirement over a rename cascade. Retirement (is_active = FALSE) frees the slug for reuse while historical assignments keep resolving — rename when the meaning genuinely stayed the same, retire when it did not.
  • One owner per tag family. Let one supervisor own the outbound tags, one own the inbound tags; a shared audit trail records every create/update/retire so “who added this?” is answerable.
  • Do not tag what a queue code already answers. If a queue gates availability on a specific wrap-up code, tagging the same fact again on every call is wasted agent effort.
cURL
Retire returns 204. Reactivate later with PATCH {"isActive": true}.

​
Troubleshooting

  • Agents report a tag missing from the picker: verify the catalog row is is_active = TRUE; the picker only renders active rows. If visibility persists, the picker re-reads the catalog on every open — an archived-then-reactivated tag reappears on the next refresh.
  • Stamp call rejects a slug: the stamp endpoint only accepts tags that resolve to an active row; a slug staged with is_active = FALSE fails with DISPOSITION_TAG_NOT_FOUND. Reactivate it and retry.
  • Duplicate-slug 409 on create: the slug is unique among active rows. Retire the old row first, or pick a different slug; converging the same slug after retirement is allowed.
  • Tag filter shows no calls in Insights: a tag with zero assignments is noise; either agents have not adopted it or the traffic genuinely stopped. Check adherence before deciding the tag is broken.

​
See also