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

# Conversation Intelligence

> How Orbit scores your conversations: sentiment, topics, quality, and resolution signals computed over agent conversations, plus the tenant-defined operators that extract custom values per thread — what is computed, where the data comes from, how long it is kept, and how to query it.

# Conversation Intelligence

Conversation intelligence is the analytics layer that sits on top of your
[conversations](/concepts/conversations). It answers two questions operators
ask after the fact: "what did the customer say and how did it go?" and "how
is my team/agent performing across all of them?" This page names what is
computed, where the source data comes from, how it is stored, and how to
pull it over the API.

## What gets computed

Orbit computes two kinds of signal over a conversation.

### Built-in analysis (automatic)

Each conversation in the agent-conversations surface is scored once in the
background for a fixed set of signals:

| Signal          | Shape                                                        | How it is produced                                                                                                          |
| --------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `sentiment`     | `positive` / `neutral` / `negative` + a 0–1 confidence score | An LLM reads a built transcript (customer/agent turns, system prompts excluded) and returns one of the three labels.        |
| `topics`        | 1–5 short topic strings                                      | The same LLM pass names the contact drivers in plain language ("billing dispute", "shipping delay").                        |
| `quality_score` | 0–10                                                         | LLM-assigned, then adjusted by objective metrics — resolved status raises it, failed status and very long threads lower it. |

The raw transcript sent to the model is truncated to control cost. When no
LLM provider is configured, or the LLM call fails, a status-based heuristic
fills the same fields (completed → positive, failed → negative) so the
dashboard never renders empty purely because the model is unavailable.

These signals feed every aggregate the dashboard and the API compute:
volume and duration aggregates, sentiment distribution over the window,
per-channel breakdown, an agent leaderboard, daily time series, top topics,
the subset of topics that are **surging** (recent-window volume spiked
against their own baseline), escalation rate, average quality score, and
two resolution metrics — `resolution_rate` (status-only completions, kept
for back-compat) and the un-gameable `solution_rate`, which only counts a
conversation when the customer explicitly confirmed resolution (CSAT,
thumbs-up, or an affirmative confirmation) or when the analysis judged
sentiment positive **and** the workflow completed. A period-over-period
`csat_delta` — current-window quality score minus the prior equal window —
is computed so operators see direction of travel, not a point-in-time score.

### Tenant-defined operators (configured)

On top of the built-in pass you can define your own **operators** — named
LLM instructions such as "intent: refund, order status, or complaint" or
"churn-risk flag". Each operator has an `outputType` (`text`, `boolean`,
`number`, `enum`, or `list`); `enum` operators carry a `choices` array. An
optional `channels` list scopes which text channels it runs on. Results are
recorded per conversation and are readable per thread. Because every active
operator adds one classifier call per message, the number of active
operators per tenant is capped. Updating an operator's instruction,
output type, or choices bumps its `version` and re-runs results under the
new definition. Operators are managed from the Inbox endpoints (see
[Endpoint families](#endpoint-families) below).

## Where the data comes from

The source of truth is the conversation record (the
[conversations model](/concepts/conversations)). For voice, the audio-yield
lane contributes recordings on the media plane, so a call thread can carry
transcripts that the same scoring pass consumes. Analysis runs in the
background — a poll against the endpoint kicks a throttled scan of
un-analyzed conversations, and the hourly server-side scheduler re-kicks
the same scan — so the first dashboard load after traffic lands may show
the newest conversations without scores yet; they fill in on the next poll.

## Storage and retention

Results are cached on the conversation record itself
(`metadata.ai_conversation_analysis`), so a conversation is analyzed once
and re-used forever — the heavy aggregate scans crack that JSONB per window
rather than calling the model again. Aggregates over the window are served
through a short stale-while-revalidate cache so a burst of dashboard polls
collapses into at most one scan; the "recent conversations" list is read
fresh every time. Operator results inherit the same per-conversation
storage, so deactivating an operator (a soft delete) retains previously
computed values while freeing its slot against the active-operator cap.
Retention of the underlying conversations follows the
[conversation-archive policy](/guides/conversation-archive); the
[message `metadata` policy](/concepts/data-model) governs what scalars are
encoded there.

## How to query the API

The endpoint lives under `/stats`:

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

* `days` — lookback window in days (default 30).
* `trigger_analysis=1` — kick the background scan without paying for the
  full aggregate fan-out (used by the server-side scheduler; useful in
  integrations too).

Responded with a single payload of every subsection — `aggregates`,
`sentiment_distribution`, `channel_breakdown`, `agent_leaderboard`,
`time_series`, `recent_conversations`, `top_topics`, `surging_topics`,
`escalation_rate`, `avg_quality_score`. Sections are computed in parallel
and a slow section degrades to its zero value instead of a 5xx, so the
dashboard keeps rendering while data fills in. Viewer-tier dashboard
sessions and API keys whose scope includes `analytics:read` can call it.

### Endpoint families

Tenant-defined **operators** (the custom scores above) are managed on the
Inbox API:

| Operation                        | Endpoint                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------ |
| List the tenant's operators      | `GET /inbox/conversation-intelligence/operators` (optionally `includeInactive=true`) |
| Create an operator (owner/admin) | `POST /inbox/conversation-intelligence/operators`                                    |
| Update an operator (owner/admin) | `PATCH /inbox/conversation-intelligence/operators/{id}`                              |
| Deactivate (soft delete)         | `DELETE /inbox/conversation-intelligence/operators/{id}`                             |
| Read results on one conversation | `GET /inbox/conversations/{id}/conversation-intelligence`                            |

The full request/response shapes are on the
[Inbox endpoint reference](/api-reference/endpoints/inbox); the operator
taxonomy is shared with the voice speech-category surface.

## Privacy and regulatory posture

Analysis runs on **your tenant's data in your tenant's schema** — the model
receives a transcript of that thread's messages, and the scored result is
stored back on the conversation record in your tenant schema (see
[tenant isolation](/concepts/tenant-isolation)). For voice, any recording
the thread consumes is governed by your
[recording-consent](/compliance/recording-consent) policy — which calls are
captured and how participants are announced — and by
[voice data residency](/compliance/voice-data-residency), which pins the
recordings to your region. Conversation transcripts and their scores
inherit the same tenant data-residency posture as the rest of your message
traffic. Deleting a conversation archive removes its cached analysis with
it. As with the other compliance topics, these are **tenant-owned
controls** — the page describes Orbit platform behaviour, not legal advice;
confirm residency and consent obligations with counsel.

## Example use cases

* **QA triage** — the agent leaderboard and the
  [quality-management program](/guides/quality-management-program) turn
  `quality_score`, `solution_rate`, and `csat_delta` into a weekly review
  loop instead of a chore.
* **Routing signals** — a `surging_topics` badge and the
  `conversation.topic_spike.anomaly_detected` event the server-side
  scheduler raises pick up an emerging contact-driver before it blows up;
  wire it into routing rules to shift capacity.
* **Custom signals** — tenant-defined operators let you tag refund intent,
  churn risk, or a compliance flag, then filter the Inbox per those values.
* **Agent coaching** — pair the conversation-level `quality_score` trend
  with the time series to focus coaching where scores move.

<Note>
  The `sentiment` label is an analytical judgment, not a routing guarantee —
  a "positive" conversation can still fail its `solution_rate` if it was
  escalated. Base routing on robust signals (status, escalation) and use
  sentiment as a QA/low-signal input.
</Note>

## Related reading

* [Conversations](/concepts/conversations) — the thread model these scores ride on.
* [Data model](/concepts/data-model) — envelope + pagination conventions.
* [Quality management program](/guides/quality-management-program) — the QA-triage walkthrough.
* [Inbox endpoint reference](/api-reference/endpoints/inbox) — operator management per thread.
* [Recording consent](/compliance/recording-consent) + [voice data residency](/compliance/voice-data-residency) — the voice-side controls the analysis inherits.