Skip to main content

​
Inbox dispositions — outcome labels on closed conversations

A disposition is the recorded outcome of a conversation — “Resolved”, “Refund issued”, “Escalated to billing”. Dispositions are the labels agents pick (or the AI judge assigns) when a conversation closes, and the axis the Distribution view, your reports, and conversation-intelligence operators query against. Dashboard: Inbox → Settings → Dispositions (owner / admin only — the label-set editor is a tenant-owned control). Base path: /api/v1/inbox/dispositions

​
1. Disposition sets vs. voice disposition tags

Three surfaces nearby answer different questions; make sure you are on the right one:
  • Inbox disposition sets (this page) — the outcome label taxonomy for digital queue conversations: chat, email, social messaging, SMS-style inbound threads. A set is one list of up to 50 labels scoped to a conversation type (inbox, voice, or any), and one set per type can be marked the default. A conversation carries one label from one set.
  • Voice disposition tags (Define and use disposition tags) — the per-call outcome tags voice agents stamp during wrap-up on voice queues, where a call can carry several overlapping tags at once. That is a separate catalog living under Voice → Disposition Tags; do not land it here.
  • Wrap-up codes enforced by a queue — the per-queue required-code gate on voice ACD queues. Disposition lifecycle rules below enforce the state transitions a disposed conversation may take; wrap-up codes gate agent availability. Different axis, different console.
If you are setting up digital-queue outcomes — “which label set does the AI judge use when it closes an email thread?” — you are on the right page. For voice-call tag stamping, use the voice guide.

​
2. Walkthrough — create and edit label sets

Disposition sets are created and edited at Inbox → Settings → Dispositions → Label sets (the first tab). Each set is a named list of labels agents and the AI judge pick from when a conversation closes.
  1. Click Create disposition set.
  2. Name the set — e.g. “Support outcomes”, “Sales call results”.
  3. Pick the conversation type the set applies to: inbox, voice, or any. The type is immutable once the set is created; a set that should apply to both digital and voice channels uses any.
  4. Add label rows. Each label has a display text (what agents see in the close picker), a slug id (resolved, refund-requested), an optional color, and an optional description. The slug auto-fills from the display text until you hand-edit the id, and must be unique within the set. The description is the guidance the AI judge reads when deciding which label fits a closed thread — “When the AI judge should pick this label”, not just a note for humans.
  5. Toggle Default for this type if this set should be the one applied automatically when a conversation of that type closes.
Constraints the form enforces inline (with the same bounds the API returns as 422s): set name up to 128 chars, up to 50 labels per set, label id must be a lowercase slug (a–z 0–9 _ -), label text up to 128 chars, description up to 500 chars, and a tenant cap of 20 sets. Click Create set. Edit an existing set from its row’s pencil icon. The conversation type is locked there (the PATCH contract omits it by design, so relabeling rows cannot turn a voice set into an inbox one). Setting a new default demotes the prior default for the same conversation type — the trial closing pipeline always uses exactly one default per type.

​
3. Distribution view — read the outcome split

The second tab, Distribution, aggregates the last 30 days of disposed conversations into a per-label breakdown. Filter it to one set or view All sets. Four summary tiles sit above the bars:
  • Total disposed — closed conversations carrying a label in the window.
  • AI auto — labels the AI judge assigned at close time, no human edit.
  • Agent manual — labels an agent stamped at close, after one of the above passes or the AI lane was skipped.
  • Override rate — the fraction of AI-auto labels an agent later corrected. A rising override rate means the AI judge’s label descriptions are vague or the taxonomy’s labels overlap; tighten the label guidance until auto stays where agents agree it should.
Each bar shows a label’s share of the total; filters update the bars inline. The panel always covers the trailing 30 days; for longer windows, query the stats endpoint (/inbox/dispositions/stats) with an explicit from / to.

​
4. AI-assigned dispositions — which role applies them

At close time two paths stamp a disposition:
  • Agent manual — the agent picks a label from the applicable set in the close dialog before the thread moves out of open. If a set that applies to the conversation’s type has a default marked, agents see only that set’s labels.
  • AI auto — when the agent closes without stamping, the AI judge reads the thread transcript and assigns a label plus a confidence score, using the label descriptions in your set as guidance. It fires on every closed conversation for which a default taxonomy is configured; if no default set exists, the AI lane skips silently. Re-open then re-close replaces the prior assignment. The judge never blocks the close path — a judge failure logs and skips rather than stalls the agent.
The override rate tile is the quality signal for the AI lane: every time an agent re-stamps a conversation the AI had labeled, the override rate counts it. Use it to decide whether to invest in better label descriptions or accept manual-only stamping for that queue. Distribution counts are lane-specific, so a team that reads “Resolved — 60% AI auto” is reading the AI judge’s calls before agent correction; an agent-written override lands in Agent manual on the next refresh.

​
5. How dispositions feed reports and conversation intelligence

Dispositions are the outcome axis several tenant surfaces slice on:
  • Reports — the Distribution tab itself, plus any saved report that groups by disposition label; auto-closed volume is split from agent-driven closes by closed_reason, so disposition mix stays meaningful even with the auto-close sweep enabled.
  • Conversation-intelligence operators — an operator scoped to a conversation can filter or group by the disposition a thread carries once closed (Conversation intelligence operators covers operator setup). Dispositions are the typed outcome the operators report against when you ask “which intents resolve on first touch?” or “which escalations land in refund-requested?”
  • Ticket automation + routing rules — both match on the stamped outcome, so a rule can route escalated-closed conversations to a senior queue or open a follow-up task when the AI judge lands unresolved with low confidence.

​
6. Lifecycle rules — which transitions a disposed conversation may take

The third tab, Lifecycle rules, defines the allowed transitions a disposed conversation may take between the three work-item states (open → pending → resolved).
  • Empty ruleset = built-in defaults apply — open ↔ pending, open → resolved, pending → resolved — and resolved closes the work item.
  • Your first rule replaces the defaults wholesale. Adding one custom edge turns off all four built-in edges; define every transition your workflow needs, including the ones the defaults covered, or agents will find paths they relied on blocked.
  • Terminal rules — a rule pointed into resolved is final and can carry two controls: an aging window (within_hours, so the move is rejected once the current state has lasted longer) and the closes work item flag the close-enforcement gate honors. Neither control exists on non-terminal edges; the form disables them rather than return a 422.
  • Caps and duplicates — up to 9 rules per tenant, and a duplicate edge (open → resolved twice) is refused inline before it can reach the API. Deleting back to zero rules reverts the tenant to the built-in defaults.
resolved is terminal — no rule can route out of it — so a lifecycle setup closes each conversation at exactly one state.

​
7. Merge rules — which thread’s dispositions survive

When two threads about the same contact collide, POST /api/v1/conversations/:id/merge folds the secondary rows into the primary. For dispositions:
  • The primary conversation’s dispositions survive. The merged (source) rows are archived with metadata.merged_into pointing at the primary; their disposition history does not transfer onto the surviving thread’s close-time record.
  • Tags and dispositions attached before merge stay attached on whatever row they were stamped on — a merged thread’s Distribution slice reads the surviving conversation only, so a label you need to persist must be stamped on the primary (the one you keep).
  • Re-stamp after merge if the surviving thread needs a label the archived source had: the label is per conversation, not per contact, and does not follow the merge.
The merge surface and its confirmation gates are documented at Conversation merge troubleshooting.

​
8. API parity

Everything the console does is available via the inbox API, so tenant automation and the dashboard stay in lock:
  • List sets — GET /api/v1/inbox/dispositions/taxonomies returns the tenant’s sets default-first; a tenant whose tables are not yet provisioned gets an empty list rather than an error.
  • Create / edit sets — POST /api/v1/inbox/dispositions/taxonomies (owner/admin, 422 on bounds) and PATCH /api/v1/inbox/dispositions/taxonomies/{taxonomyId} (rename, relabel, set default — the PATCH omits conversation_type by design).
  • Read distribution — GET /api/v1/inbox/dispositions/stats with optional from / to / taxonomy_id; returns the per-label split plus the AI-auto / agent-manual / override-rate summary.
  • Lifecycle rules — GET /api/v1/inbox/dispositions/lifecycle/rules + POST / DELETE for rule CRUD; the ruleset is what the close-enforcement gate consults.
Full endpoint contract: Inbox endpoints — dispositions.

​
See also