AI Insights

An AI insight is a piece of information a language model extracts from a conversation after that conversation has ended: a summary, a topic, a churn risk level, or anything else you define in your own business terms.

Two pages sit beside this one. Conversation Attributes covers what both kinds have in common: the edition, the switch that turns them on, and where recorded values surface. Custom Attributes covers the other tab, for values a flow already knows and writes itself. This article is about the AI Insights tab only: the built-in insights, defining your own, ordering them, when they run, generating them again after a failure, and editing or deleting a definition.

What an insight is, and what it is not

An insight is produced by a model, once, after the conversation is over. It reads the whole transcript and answers the question your definition asks. You build nothing in the flow for it, and the conversation itself is not affected: insights describe what happened, they do not change what the assistant says while it is happening.

Insights that already exist are never recomputed. Adding a definition, editing its possible values, changing its score range, disabling it or reordering the list changes nothing about conversations that already have values, and there is no way to apply a change to past conversations in bulk. Only conversations that end after the project is published carry the change. The exception is a conversation left with no insight values, usually because generation failed: you can generate its insights from its detail page.

The built-in insights

Every project starts with these definitions. They cannot be deleted, but each has its own enable switch and can be turned off like any other.

That is also the order they ship in, and it can be changed. The built-in names contain spaces; names you create cannot.

The definitions screen

Open the project settings gear, then Conversation Attributes. The AI Insights tab is the first of the two.

1. Tabs: AI Insights (this tab) and Custom Attributes. Both are saved separately.

2. + Add AI Insight: Adds a new definition row.

3. Drag handle: Moves a definition up or down the list.

4. Name: The insight's identifier, and the name its column and filter carry everywhere else. Up to 100 characters, starting with a letter or an underscore, letters, digits and underscores only, unique within the project ignoring case.

5. Description: What this insight should capture. This text is written for the model, not for your colleagues, so be concrete about what counts and what does not. Up to 1,000 characters.

6. Output Type: What shape of answer the model must return. Required, and fixed after the first save.

7. Possible Values: Only for the category types. Type a value and press Enter for each one. The score types show a minimum and a maximum here instead.

8. Enable switch: Whether this insight is evaluated at all. A disabled insight is not sent to the model and produces no values while it is off. On a row you have just added, the switch stays inactive until you save the page.

9. Delete: Only on definitions you created.

Defining a custom insight

The output type is the important choice, because it is what constrains the model: the possible values become the only answers the model may return, a score range becomes the only numbers it may return, and a list type is what allows more than one answer.

💡 Tip: If anyone will ever filter or count by this insight, define it as a category or a score type. Only those two can be filtered, which rules out Summary, Topic, Conversation Results, Actions and Improvement Areas, and any free text definition of your own. A question like "does this conversation need escalation" is worth far more as a category with three values than as a sentence.

Click Save, then publish the project when you are ready for the definitions to apply to live traffic.

Ordering the list

Drag a definition by its handle to move it. The order you set is the order the insights appear in on the conversation detail screen, in the column picker on the Conversations page, in the AI Testing dataset filter picker and in the export's column list. Like every other change here, it is made on the Draft version and applies once the project is published.

When insights run

Insights run automatically once, at the moment the conversation ends: when the customer's session is closed or the flow finishes it. The full transcript is sent to the model, and every enabled definition, built-in and custom, is evaluated from it. If that run fails, you can start it again by hand from the conversation's detail page.

The conversation appears on the Conversations page as soon as it ends, but its values arrive a little later, and a long conversation with many definitions takes longer than a short one. Nothing on screen indicates that generation is in progress and the page does not refresh itself, so reopen or reload the conversation to see the values.

Reading the values in the Post Session Flow. Insights are generated as the conversation ends, which makes the Post Session Flow the one place a flow can act on them. Each built-in insight arrives in its own context variable: InsightsSummary, InsightsTopic, InsightsChurnRisk, InsightsConversationResult, InsightsNonResolutionRisk, InsightsActions and InsightsImprovementAreas. Everything you defined yourself arrives together in InsightsCustom, as JSON. They are read like any other context variable, so the flow can branch on a churn risk of High, or pass a summary on to another system.

If a value never appears. A free text insight can legitimately come back with nothing to report, so a single empty field is not a fault, and the conversation counts as generated. When generation fails as a whole, or a conversation ends with no insight values at all, its detail page offers Generate AI Insights. Nothing on the Conversations list marks such a conversation; the button on its detail page is the only sign.

Generating insights again after a failure

1. Open Insights > Conversations and click the conversation's Date link.
2. Under the AI Insights heading, click Generate AI Insights.

The button is disabled while the run is in progress. When it succeeds, the values appear under the heading and the button disappears; custom attribute values on the conversation are not touched. When it fails, an error dialog opens, nothing is saved, and the button stays so you can try again. Each run is a model call and is counted in token and cost reporting like the automatic one.

The button appears only when the conversation has no insight values, AI Insights is on for the project, at least one insight definition is enabled, and the conversation has at least one text message. It works on one conversation at a time. It is greyed out while the conversation is still being masked, and when the tenant's Add-On AI Features LLM settings are incomplete; in that case hovering it shows a tooltip, and the settings have to be completed first.

Where the values appear

Insight values are stored on the conversation and show up on the conversation record, as columns on the Conversations page, as filters there and on AI Testing datasets, and in the export. Conversation Attributes covers all of these.

A single conversation's values can also be read from outside the product through the external session metrics API, GET /api/external/sessions/metrics/ai-insights/{externalConversationId}, which returns the built-in insights as named fields plus a list of your custom ones. This endpoint sorts the custom insights alphabetically by name rather than by your configured order, and joins a list-valued insight into a single string.

The Daily Conversation Report API also returns each conversation's AI Insight values, each with its name, output type and a list of values.

Editing and deleting a definition

Everything except the name and the output type stays editable: the description, the possible values, the score range and the enable switch. An edit reaches the automatic run only once the project is published, while a Generate AI Insights run uses the definitions as they are when you click, unpublished changes included.

Definitions that AI Testing depends on are protected. An insight used as a filter in a dataset cannot be deleted, and a possible value used by a dataset filter cannot be removed, until the dataset stops using it. Turning the project's Conversation Attributes switch off while datasets use insight filters is allowed, but you are asked to confirm first, because those filters are then ignored when the tests run.

Limits and naming rules