> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telnyx-Managed Insights

> Use built-in insights from Telnyx — Agent Instruction Following and User Satisfaction — to measure assistant quality out of the box, no custom configuration needed.

## Overview

Telnyx provides a set of **built-in insights** that measure assistant quality out of the box — no prompt engineering or schema design required. These are called **Telnyx-managed insights** (also referred to as *default* insights in the API and Portal).

Unlike [custom insights](https://developers.telnyx.com/docs/inference/ai-insights/creating-insights) that you define yourself, Telnyx-managed insights are maintained by Telnyx, have consistent scoring rubrics, and are available to every account. You just assign them to an assistant's Insight Group and start getting results.

## Available insights

### Agent Instruction Following

Measures how well your assistant followed its system prompt and tool-use instructions during the conversation.

| Score     | Meaning                                            |
| --------- | -------------------------------------------------- |
| Excellent | Followed all instructions precisely                |
| Good      | Followed instructions with minor deviations        |
| Fair      | Missed one or more instructions but stayed on task |
| Poor      | Significantly deviated from instructions           |
| N/A       | Could not be evaluated for this conversation       |

**When it matters:** Any time you care about prompt adherence — complex assistants with many tool instructions, compliance-sensitive flows, or when debugging unexpected assistant behavior.

### User Satisfaction

Estimates how satisfied the caller was with the conversation based on their responses, tone, and engagement signals.

| Score     | Meaning                                      |
| --------- | -------------------------------------------- |
| Excellent | User was clearly satisfied and engaged       |
| Good      | User was generally satisfied                 |
| Fair      | User was neutral or mixed                    |
| Poor      | User was frustrated or dissatisfied          |
| N/A       | Could not be evaluated for this conversation |

**When it matters:** Customer support, sales calls, any voice flow where caller experience directly impacts business outcomes.

<Note>
  The set of Telnyx-managed insights may grow over time. Check the Insight Group configuration in the Portal for the current list.
</Note>

## Enabling Telnyx-managed insights

### Step 1: Add to an Insight Group

1. Navigate to [AI Insights](https://portal.telnyx.com/#/ai/insights) in the Portal.
2. Go to the **AI Insight Groups** tab.
3. Create a new group or edit an existing one.
4. In the insights dropdown, search for **Agent Instruction Following** and **User Satisfaction**.
5. Add both (or whichever you need) to the group.
6. Save the group.

See [Insight Groups](https://developers.telnyx.com/docs/inference/ai-insights/insight-groups) for full group configuration details.

### Step 2: Assign the group to your assistant

1. Open your assistant in the [Portal](https://portal.telnyx.com/#/ai/assistants).
2. Go to the **Analysis** tab → **Insights** sub-tab.
3. Select the Insight Group you created above.
4. Save the assistant.

### Step 3: Have conversations

Insights run automatically after each conversation completes. Results appear in two places:

* **Per-conversation** — in the Conversation History tab for each individual call.
* **Over time** — in the Insights Over Time tab as aggregated daily charts.

## Viewing results

### Per conversation

1. Open your assistant → **Analysis** tab → **Conversation History** sub-tab.
2. Click any conversation.
3. Scroll to the **Insights** section to see the scores for each insight in your group.

Each result includes the score (e.g. "Good") and any additional detail the insight provides.

### Over time (7-day trend)

The **Insights Over Time** sub-tab (third tab under Analysis) shows a **stacked-bar chart** of daily score counts for the last 7 days, scoped to the current assistant.

**What the chart shows:**

* One bar per day (UTC) for the last 7 days.
* Each bar is segmented by score value, color-coded:
  * **Poor** — red
  * **Fair** — amber
  * **Good** — green
  * **Excellent** — blue
  * **N/A** — gray
* Bars are stacked bottom-to-top with N/A pinned to the bottom and Poor through Excellent ascending, so the best results sit on top.

**How to use it:**

1. Use the **Insight** dropdown to select which Telnyx-managed insight to view (only Telnyx-managed insights appear here — custom insights are excluded).
2. Read the chart left to right to spot trends — is the "Excellent" segment growing or shrinking over the week?
3. Check for sudden shifts on specific days, which often correlate with config changes or new assistant versions.

### Comparing assistant versions

Toggle **Compare by assistant version** above the chart to split the data into separate charts — one per assistant version. This creates a small-multiples layout where each version gets its own labeled chart.

<Note>
  Version comparison uses `metadata.assistant_version_id` to attribute conversations to versions. Conversations without a version ID are grouped as "Unknown version".
</Note>

This is useful when:

* You've published a new version and want to see if quality metrics improved or regressed.
* You're A/B testing different prompt configurations across versions.
* You want to confirm a fix didn't introduce new issues before promoting a version.

## Tips for getting value from Telnyx-managed insights

### Spotting regressions after a change

After updating your assistant's prompt, tools, or voice settings, watch the over-time chart for the next few days. If the "Poor" or "Fair" segments grow while "Good" or "Excellent" shrink, the change may have hurt quality.

### Correlating with volume

Taller bars mean more conversations. A spike in volume can amplify small score shifts — check the raw counts in the chart tooltip before drawing conclusions.

### Understanding N/A rates

A large gray (N/A) segment means the insight frequently couldn't be evaluated. For Agent Instruction Following, this may indicate conversations that were too short or didn't trigger tool use. For User Satisfaction, it may mean the conversation lacked enough user signal (e.g., one-sided calls). If N/A rates are high, check whether your assistant is handling the conversation types you expect.

### Using scores alongside conversation history

The over-time chart tells you *when* quality shifted. The conversation history tells you *why*. When you see a dip, switch to Conversation History, filter to that day, and review individual conversations to find the root cause.

## Troubleshooting

### Chart shows "No insight data recorded"

* Confirm the Insight Group includes Agent Instruction Following or User Satisfaction.
* Confirm the group is assigned to the assistant in the Analysis tab.
* Confirm the assistant has had conversations in the last 7 days.
* Confirm conversations completed successfully — insights run after the conversation ends.

### Scores seem inconsistent

Telnyx-managed insights use AI evaluation, which considers the full conversation context. Scores can vary based on conversation length, topic complexity, and user behavior. Look at trends over multiple days rather than individual conversations.

### Version comparison shows "Unknown version"

Conversations that occurred before version tracking was enabled (or that lack version metadata) are grouped as "Unknown version." Ensure your assistant has published versions and that conversations are attributed correctly.

## Related resources

* [Creating Insights](https://developers.telnyx.com/docs/inference/ai-insights/creating-insights) — Create your own custom insights.
* [Structured Insights](https://developers.telnyx.com/docs/inference/ai-insights/structured-insights) — Define JSON schemas for consistent data extraction.
* [Insight Groups](https://developers.telnyx.com/docs/inference/ai-insights/insight-groups) — Organize insights and configure webhooks.
* [Use Cases](https://developers.telnyx.com/docs/inference/ai-insights/use-cases) — Industry-specific insight examples.
* [Voice Assistant Configuration](https://developers.telnyx.com/docs/inference/ai-assistants/no-code-voice-assistant#insights) — Assigning insight groups to assistants.