Telnyx-Managed Insights

​

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 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. 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. When it matters: Customer support, sales calls, any voice flow where caller experience directly impacts business outcomes.

​

Enabling Telnyx-managed insights

​

Step 1: Add to an Insight Group

1. Navigate to 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 for full group configuration details.

​

Step 2: Assign the group to your assistant

1. Open your assistant in the Portal.
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. 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 — Create your own custom insights.
• Structured Insights — Define JSON schemas for consistent data extraction.
• Insight Groups — Organize insights and configure webhooks.
• Use Cases — Industry-specific insight examples.
• Voice Assistant Configuration — Assigning insight groups to assistants.