> ## 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.

# Read the Conversation Intelligence panel

> Operator guide to Insights → Conversations — the AI-analyzed aggregate view across every channel: sentiment distribution, channel mix, recent threads, the agent leaderboard, and how to drill from an aggregate back to a single thread.

# Conversation Intelligence

Conversation Intelligence answers one question: **how are your customers' conversations trending, and where is sentiment drifting?** Open **Insights → Conversations** in the Orbit console to see every conversation your AI agents and human teams handle across SMS, WhatsApp, email, and voice rolled up into one panel — sentiment distribution, channel mix, recent threads, and a per-agent leaderboard. It is the aggregate counterpart to the per-thread views: read it first, then drill into it.

Three adjacent surfaces answer different questions — the [Picking the right surface](#picking-the-right-surface) section below settles which one to reach for.

## What the panel computes

The panel reads one analytics payload — `GET /api/v1/stats/conversation-intelligence` — and renders six sections from it:

* **KPI strip.** Total conversations, average messages per conversation, resolution rate, solution rate, average duration, and quality score (with a period-over-period delta when the backend has a scored prior window). Read resolution and solution side by side: resolution counts conversations marked complete (gameable — an agent that auto-closes threads drives it to 100%); solution counts only threads where the customer confirmed resolution or the workflow closed with positive sentiment. When they diverge, trust solution.
* **Conversation volume area chart.** Daily conversation count over the selected window — pick 24h for incident triage, 7d/30d (default)/90d/12m for trend work, or a custom calendar range.
* **Sentiment distribution donut.** The `sentiment_distribution` aggregate — how many conversations in the window the AI analyzer classified as positive, neutral, or negative. Coverage notes below.
* **Channel breakdown bar chart.** The `channelBreakdown` aggregate — how many conversations each channel (SMS, WhatsApp, email, voice) contributed to the window.
* **Recent conversations table.** The `recent_conversations` list — the latest threads across all agents and channels, each carrying the agent name, channel, status, and (when the analyzer has classified it) sentiment. Default-capped to the most recent 25 with a **View all** expander.
* **Agent leaderboard.** Agents ranked by conversation volume, resolution rate, average handle time, CSAT proxy, and average token spend — the drill-in for "which agent is generating this sentiment."

Below the sentiment donut, an **escalation rate** badge flags the fraction of conversations the AI analyzer marked negative; past 20% it renders as an error badge instead of an outlined one.

Sentiment is computed from conversation text — the text channels (SMS, WhatsApp, email, web chat) always contribute. Voice conversations contribute only when voice transcription is enabled for your tenant; without transcription enablement the voice channel has no text to classify, so the sentiment widget undercounts the true voice share. The channel-mix chart still reports voice volume — the caveat is only about sentiment coverage. Platform-managed defaults set the transcription flag; see the [voice transcription guide](/guides/stt-playground) for how to enable it.

## Reading the sentiment donut

The donut splits the window's sentiment distribution into three segments: **Positive** (green), **Neutral** (slate), and **Negative** (red). Each legend entry pairs its color swatch with a non-colour glyph — triangle-up for positive, square for neutral, triangle-down for negative — because a color-only legend collapses Positive and Negative into the same shape for red/green colour-blind readers on your team. If you only export the summary CSV, the same three counts land in the `Sentiment distribution` section of the file so a screen-reader workflow loses nothing.

Hover a segment to see its exact count (formatted compact — `1.2K`, `4.5M`) rather than the donut percentage; count is the number that survives an export.

## Channel breakdown

The channel chart next to the donut shows what fraction of the window's conversations came in over SMS, WhatsApp, email, and voice. Use it as the mix check before you act on the sentiment donut: if WhatsApp is 80% of your volume, a sentiment dip is a WhatsApp problem, not a portfolio problem. Consecutive bars share the chart palette, so the chart is categorical — read it as "how much each channel contributes," not "how good each channel is."

The single-channel bar labels capitalize (the chart's Y-axis formatter uppercases the first letter), so `sms` renders as **Sms** in narrow panels — channel names come from the same casing the API returns.

## Recent conversations — back to the per-thread view

Aggregate widgets answer the *where*; the **Recent Conversations** table answers the *which thread*. Each row carries the agent name, its channel badge, the conversation status pill, and a sentiment badge when the AI analyzer has classified the thread — newest first. Use it to jump from "negative sentiment spiked this week" to the actual conversations driving it. From a row you can continue into the per-turn debug view or the unified interaction list, but for most operators the next step is simply opening the agent whose rows keep showing up.

**View all {count} conversations** expands past the default 25-row cap; the same cap applies to the agent leaderboard above it.

## Worked example: the week-over-week sentiment dip

You are a support lead. Monday's roll-up shows a **Negative ▼** slice that doubled, from 4% to 9% of the 7d window.

1. **Check the channel mix.** The channel bar shows WhatsApp still dominates; nothing about the mix changed — so the dip is not a channel migration.
2. **Scan the agent leaderboard.** One agent — *Order Status Bot* — moved from 92% to 61% resolution. That is where the negative rows concentrate.
3. **Open Recent Conversations and filter visually.** The rows tagged *Order Status Bot* carry red **Negative** badges; expanding to all rows confirms the cluster is on this one agent, not spread across the fleet.
4. **Drill into the agent.** Click the agent name in the leaderboard to open its detail page; the [agent conversation debug guide](/guides/agent-conversation-debug) walks the per-turn view from there.
5. **Export a snapshot if you need an offline record.** The **Export CSV** button emits a self-describing file (range header, summary KPIs, sentiment counts, per-channel counts) so the delta you found survives attaching to a ticket.

Conversely, if the leaderboard had stayed flat while Negative rose, the question would shift from "which agent" to "which topic" — that flips you to the [Topic Intelligence](#picking-the-right-surface) surface below.

## Picking the right surface

Three surfaces cover adjacent ground; the pick-order is:

* **Conversation Intelligence (this page).** Aggregate sentiment, channel mix, and agent ranking across every channel — "how are conversations trending, and which agent is driving the trend."
* **[Interaction Search](/guides/interaction-search).** A filterable, recency-ordered **list** over every message conversation and every voice call — "find and audit individual threads." Reach for it when you need a specific thread, not a trend.
* **[Topic Intelligence](/guides/insights-topic-intelligence).** Aggregated contact **reasons** — "what customers contact us about and is it rising." Reach for it when sentiment is fine but the inbound mix is shifting.

If you want per-turn agent behavior, drill via the leaderboard into the [agent conversation debug](/guides/agent-conversation-debug) view; this panel stays aggregate on purpose.

## API contract

`GET /api/v1/stats/conversation-intelligence` returns the payload the page renders. Accepts the trailing-window query param `?days=` (integer, 1–365, default 30). The response is the standard `{ data, meta }` envelope with `data` carrying `aggregates`, `sentiment_distribution`, `channel_breakdown`, `agent_leaderboard`, `time_series` (volume), and `recent_conversations`. A fresh tenant receives a handled `200` with zeroed aggregates, so the read is safe to poll. Both Clerk sessions (dashboard) and API keys with `analytics:read` reach it — use the key form when you wire the read into a warehouse.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/stats/conversation-intelligence?days=30" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

| Field                    | What it is                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `aggregates`             | KPI strip: `total_conversations`, `avg_messages_per_conversation`, `resolution_rate`, `solution_rate`, `avg_duration_seconds`, `csat_delta` |
| `sentiment_distribution` | counts per `positive` / `neutral` / `negative` for the window                                                                               |
| `channel_breakdown`      | array of `{ channel, count }` ranked by contribution                                                                                        |
| `agent_leaderboard`      | ranked agents with `conversation_count`, `resolution_rate`, `avg_handle_time_seconds`, `csat_proxy`, `avg_tokens`                           |
| `time_series`            | daily `conversation_count` (or `count`) for the volume chart                                                                                |
| `recent_conversations`   | latest threads with `agent_name`, `channel`, `status`, `sentiment`, `message_count`, `total_tokens`, `quality_score`, `started_at`          |

## See also

* [Topic Intelligence](/guides/insights-topic-intelligence) — aggregated contact reasons across channels.
* [Interaction Search](/guides/interaction-search) — the unified per-thread list across messaging and voice.
* [Agent conversation debug](/guides/agent-conversation-debug) — per-turn agent behavior once a leaderboard row is implicated.
* [Insights dashboards](/guides/insights-dashboards) — the catalog of every other Insights surface.
* [Sentiment portfolio](/guides/sentiment-portfolio-reading) — the how-customers-feel counterpart when sentiment itself is the question.