> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand and use Contact reasons

> Classify why customers are contacting you — auto-assigned reasons, categories, urgency, and channel mix — and use the dashboard for staffing, deflection, and failure detection.

# Contact reasons taxonomy

Contact reasons tells you why customers are contacting you at the volume level. Every inbound conversation that lands in your omnichannel inbox is classified — the specific reason (for example `billing_query` or `where_is_my_order`), the coarse triage category it belongs to, its urgency, and the channel it arrived on. The dashboard at **Insights → Contact Reasons** in the Orbit console rolls those classifications up into volume and trend views, so you answer "what is driving our contact volume this month?" from data instead of anecdote.

The same aggregates are available over the API at `GET /api/v1/analytics/contact-reasons` — see the [Insights API reference](/api-reference/insights) for the full response shape.

## What the surface captures

The dashboard answers five questions, each as its own card or chart:

* **Classified conversations** — how many conversations in the window carried a classification. Only classified conversations count toward the totals and percentages; conversations the classifier skipped (very short messages, or workspaces that opted out) are excluded from the denominator so the shares stay honest.
* **By reason** — the fine-grained reason table, sorted by volume, with each reason's share of the window and how many of its conversations were tagged high-urgency. Twenty-five reasons fit in the table; the long tail still counts toward the totals.
* **By category** — the coarse triage axis the reasons roll up into. Use it for the one-sentence answer to "what kind of contact volume do we have?"
* **By urgency** — the low / medium / high distribution across the window. The high-urgency share is also a headline tile: a spike there means something is wrong regardless of total volume.
* **By channel** — which surface (WhatsApp, SMS, email, chat, and so on) drives the volume, with a per-channel high-urgency count next to it.
* **Classified volume over time** — the area chart of classified volume, bucketed hourly on the 24-hour view and daily otherwise. Use it to catch the day a reason started climbing, not just that it climbed.

A **Why conversations escalate** panel sits below the mix breakdowns. That is a different question — not "why are customers contacting us" but "why did conversations escalate past the AI or first-line team" — so it carries its own time-range selector and its own table of escalation reason codes with the median time each took to resolve.

## How reasons get assigned

### Automatic classification

Auto-categorize is on by default. When a new inbound message lands, its body is passed to a language model that classifies the conversation: the reason (a fine-grained intent such as `billing_query`), the category (the coarse triage bucket), and the urgency (low, medium, or high). Everything on the dashboard above is computed from those automatic labels — no tagging project, no taxonomy onboarding, no agent homework.

Because auto-categorize sends inbound message bodies to a third-party LLM, it is a tenant-owned control: turn it off under **Settings → Compliance → Inbox AI privacy** if your regulated content must stay off the LLM hop. With auto-categorize off, no new classifications are written and Contact reasons shows only what was classified while it was enabled — the rest of the inbox keeps working either way. Conversations that come back with no confident reason appear in the breakdowns as `unclassified`, and a rising unclassified share is itself a signal (see the worked example below).

### Manual taxonomy — escalation reason codes

The escalation panel works on a separate, human-assigned axis. When a conversation escalates, whoever escalates it records a reason code; the panel groups escalations by those codes with the median escalation-to-resolution time for each, plus a `(no reason code)` bucket for escalations recorded without one. Two operational rules follow:

* Keep the reason-code list short and stable. Codes that describe the *resolution bottleneck* ("needs supervisor approval", "refund above agent limit") aggregate well; free-text one-offs do not.
* Watch the `(no reason code)` bucket. If it grows, your escalation hygiene is degrading — the panel is only as useful as the codes people actually pick.

Treat the two taxonomies as complements: the automatic classification reads inbound demand before anyone touches it, the manual codes explain what the team could not resolve on the first pass.

## Reading the dashboard and trends

Open **Insights → Contact Reasons**. The page is read-only, refreshes roughly once a minute, and is available to the owner, admin, developer, and viewer roles.

1. **Pick the window** — 24h, 7d (default), 30d, or 90d from the selector in the header. Use 24h for incident triage ("is this spike still happening right now?") and 30d or 90d for staffing and trend decisions, where a single day should not move the numbers.
2. **Read the headline tiles first.** Classified conversations tells you whether the window has enough data to trust; Top reason names the dominant driver and its share; High-urgency share flags severity independent of volume; Active channels counts the surfaces contributing.
3. **Check the reason table before the category row.** Categories smooth over detail — two reasons inside "billing" can need opposite responses. The High-urgency column in the reason table is the fastest route to "which specific thing is on fire."
4. **Read the trend chart per reason direction, not just total volume.** A flat total hiding a surge in one reason and a decline in another is normal here — the table tells you which reason moved, the chart tells you when it started.
5. **Compare channels last.** Channel mix changes slowly; when it changes abruptly, the cause is usually operational (a campaign sent, a number ported, a widget relaunched), not a taxonomy shift.

The API (`GET /api/v1/analytics/contact-reasons?window=30d`) returns the same five breakdowns plus the trend in one response, with an optional `channel` query parameter that narrows every breakdown to a single channel — useful when you route "why is WhatsApp volume high this month?" into your own reporting.

## Operational uses

**Staffing.** The category and channel rows are a capacity plan in waiting: if "shipping status" is 40% of volume on WhatsApp, that is a deflection candidate, not a hiring request. Staff against the 30d trend, not the 24h spike.

**Deflection.** The reason table is your deflection backlog, already sorted by volume. A high-volume, low-urgency reason with a mechanical resolution path belongs in a flow or an AI agent; [AI containment](/guides/ai-agent-rollout-pipeline) then tells you whether the deflection actually took. A reason that keeps its volume after you shipped the deflection has a bad resolution path, not a missing one.

**New failure modes.** The classification adapts to whatever customers write, so the dashboard is also an early-warning surface: a reason absent from last month's table that enters this month's top five is a product or fulfillment event you have not heard about through the queue yet. The high-urgency share tile moves before volume does — treat a doubling of that share as an incident signal even when totals look normal.

**Escalation discipline.** In the escalation panel, sort by count to find the bottleneck, then by median resolution time to find the expensive one. A reason code with low count and a very high median time is a process gap (nobody owns it); high count with a low median is routine, and automatable.

## Worked example

A subscription retailer opens Contact reasons at the end of November with the 30d window:

1. The **Top reason** tile reads `where_is_my_order` at 34% of 12,000 classified conversations, and the trend chart shows the climb started on the 14th — the day a carrier integration silently began dropping tracking webhooks. That pairing (reason plus start day) is the diagnosis: not "the holidays are busy", but "tracking data stopped reaching customers."
2. The **High-urgency share** tile has doubled to 18% while total volume rose only 9%. The urgency table confirms most of that surge sits on `where_is_my_order`, so the severity is concentrated, not diffuse.
3. In the **By channel** row, WhatsApp carries 60% of the new volume — matching where the retailer sends delivery notifications, so the fix list starts with the tracking webhook and the proactive notification flow, not queue staffing.
4. The **Why conversations escalate** panel shows `carrier_exception` with a median resolution time of 3h40m against a 45-minute org median — the slow lane that turns a data outage into contact volume.

The retailer fixes the webhook integration, ships an AI-agent deflection for order-status lookups grounded in the tracking API, and watches the next two windows: `where_is_my_order` falls out of the top five, and the containment dashboard confirms the deflection rates. None of that sequence required re-tagging a single conversation by hand.

## See also

* [Insights dashboards](/guides/insights-dashboards) — the full Insights surface catalogue, including Topic Intelligence for per-topic outcomes (CSAT, deflection, handle time)
* [Insights API reference](/api-reference/insights) — the `contact-reasons` endpoint shape and query parameters
* [Inbox AI copilot](/guides/inbox-ai-copilot) — the per-conversation side of the same classification signal