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, 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 are also never recomputed. Adding a definition, editing its possible values, changing its score range, disabling it or reordering the list changes nothing about conversations that have already ended, and there is no way to backfill an insight onto past conversations. Only conversations that end after the project is published carry the change.

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

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 necessarily a fault. A failed generation looks the same: if the model call times out or the tenant's LLM configuration is missing or incomplete, the conversation is stored with no insight values and there is no error state or badge to say so. If insights stop appearing across the board, check the tenant's LLM configuration 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.

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 applies only to conversations that end after the project is published.

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