Core concepts
Public beta
Conversation Insights, including the APIs, is currently available as a public beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.
Conversation Insights is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.
Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.
Conversation Insights aggregates conversational outcomes into queryable business metrics. Use it to discover the data available across your conversations and to aggregate your conversation metrics.
Conversation Insights helps you answer the question: "what is happening across all my Conversations?" An outcome is a property of a whole conversation, such as whether it was resolved, whether it escalated, or whether it met your compliance criteria. Conversation Insights rolls those outcomes up across your entire conversation volume so that you can measure and compare them.
Supervise AI agents with Conversation Intelligence and Conversation Insights
Conversation Insights supports AI agent supervision. Track how often your AI agents resolve tasks and hallucinate across all your conversations, using Twilio-authored operators (public beta) or your own custom operators. To get started, see Supervise AI agents.
Producing those aggregate answers has traditionally meant building a pipeline: pulling data out of each product, modeling it, and maintaining the joins as those products change. Conversation Insights performs that assembly for you and exposes the result through a query API.
This page explains the model behind it. Conversation Insights uses a semantic data model based on OLAP (Online Analytical Processing) concepts: the cubes your data is organized into, how those cubes are layered, and the measures and dimensions you use to query them.
A cube is a collection of related data organized for analysis. Each cube contains measures and dimensions that you can query together. Conversation Insights provides the following cubes:
| Layer | Cube | Description |
|---|---|---|
| Gold | ConversationSummary | One row per conversation, with metadata, participant counts, and operator results such as sentiment, task completion, and hallucinations rolled up into a single record. |
| Silver | Conversation | Conversation metadata from Conversation Orchestrator, including participant details. |
| Silver | OperatorResult | Results from intelligence operators run on conversations. |
Conversation Insights organizes its cubes into gold and silver layers, following the medallion model common in analytics data modeling.
-
Gold (ConversationSummary): Holds exactly one row per conversation, with every attribute as a single value on that row. Because the row and the conversation are the same thing, you can combine attributes from across the conversation in one query without double-counting, and counting rows counts conversations.
The gold cube is analytics ready. One row per conversation is the shape that data warehouses, BI systems, and analytics tools expect, so you can load it into your reporting stack with Data Destinations and start building against it without first joining data from several sources.
-
Silver (Conversation, OperatorResult): Keeps each underlying record at its own grain, so a single conversation can produce several rows in each of them. A conversation has multiple participants, and an intelligence configuration can run multiple operators. This shape preserves the individual records for detailed analysis, and it means a new custom operator adds rows rather than requiring a schema change. It also means row counts and conversation counts aren't the same number.
What gold and silver mean here
In Conversation Insights, gold and silver describe the shape of the data rather than how refined it is. Both layers are conformed, query-ready, and reflect final conversation state. Silver isn't staging data, and it isn't less reliable than gold. Neither layer is better than the other: gold answers questions about conversations as units, and silver answers questions about what happened inside them.
Conversation Insights doesn't expose a bronze layer of raw events. To work with raw product events, use Event Streams.
Choosing a cube is less about how complex your query is than about the vantage point you want to analyze from. Each cube anchors analysis on a different resource, and the cube you pick determines what a single row represents.
- Anchor on the conversation when you want to treat conversations as units: how many closed, what their sentiment was, whether the customer's task was resolved, or how they divide between AI and human agents. Use ConversationSummary.
- Anchor on the participant when your question is about who took part in a conversation. Use Conversation.
- Anchor on the operator result when you want to explore Conversation Intelligence output directly: which operators ran, what each one returned, and which knowledge base informed them. Use OperatorResult.
The following table maps common questions to a starting cube.
| Your question | Cube | Why |
|---|---|---|
| How many conversations closed last week? | ConversationSummary | One row per conversation, so the count is a conversation count. |
| How do conversations with AI agents compare to conversations with human agents? | ConversationSummary | HasAIAgent and HasHumanAgent flag the whole conversation. |
| What share of AI agent conversations were resolved? | ConversationSummary | TaskCompletion and HasAIAgent are on the same row. |
| Which resolved conversations contained a hallucination? | ConversationSummary | TaskCompletion and HasHallucination can be filtered together in one query. |
| How is my own AI agent quality score trending week over week? | ConversationSummary | Register the score your custom operator produces as a custom measure, then average it by CreatedDate.week. |
| What is the average score my custom lead score operator produced? | ConversationSummary | Custom measures are available here at one value per conversation. |
| How do conversation outcomes relate to my CRM or order data? | ConversationSummary | Sync it to your data warehouse and join on ConversationId or CustomerProfileId. |
| Which operators ran, and what did each one return? | OperatorResult | Each operator result keeps its own row, with the operator name and label. |
If you are unsure where to start, use ConversationSummary. It answers the widest range of questions with the least assembly, and you can move to a silver cube when you need the individual records behind a number.
Each query targets a single cube. You can't combine measures and dimensions from two cubes in one request, so to bring results together, run a query per cube and join them in your own application on ConversationId.
Measures are numeric values that can be aggregated. Use measures to count, sum, or calculate statistics across your data. For example, Conversation.Count returns the count of unique conversations.
Each cube ships with built-in measures, and you can add your own. Registering a numeric field from a Conversation Intelligence custom operator as a custom measure makes it aggregatable in the same way, so a lead score or QA rating your operators produce becomes queryable across your whole conversation volume. See Define and use custom fields.
Dimensions are attributes that describe your data. Use dimensions to filter results or group measures into categories. For example, Conversation.ConversationStatus contains the status of the conversation.
The ConversationSummary cube contains one row per conversation, combining data from across the Conversations layer into a single record. A conversation can span several channels, involve several participants, and have several intelligence operators run against it. The summary cube resolves all of that into one row, with one value per attribute.
Two products contribute data today:
- Conversation Orchestrator provides orchestration state, including status, channels, participants, and the created and closed timestamps.
- Conversation Intelligence provides operator results, such as the sentiment of the conversation, whether the customer's task was completed, and whether the agent hallucinated.
More data sources are planned
Additional Conversations layer products are planned as sources for this cube, including customer profile traits from Conversation Memory and the knowledge that informed a conversation from Enterprise Knowledge. Conversation Memory is already represented by CustomerProfileId, which you can use to join this cube to your own profile data. To run that join in your warehouse, sync the summary with Data Destinations.
Three kinds of normalization reduce a conversation to a single row.
Participants become counts and flags. Rather than one row per participant, or numbered participant columns, the cube records how many participants took part, which you can aggregate with the ParticipantsSum, ParticipantsAvg, ParticipantsMin, and ParticipantsMax measures. Two boolean dimensions, HasHumanAgent and HasAIAgent, record whether at least one human agent or AI agent took part. A conversation handed off between an AI agent and a human agent has both set to true. It also records CustomerProfileId, the Conversation Memory profile identifier of the customer participant.
Repeated operator runs collapse to the latest result. If an operator runs several times during a conversation, the summary row holds the most recent result. The cube reflects the final state of the conversation rather than a history of operator executions. The silver OperatorResult cube keeps every run as its own row, so the same measure can return a different aggregate there. See Multiple results in one conversation.
Each operator result becomes its own attribute. Every value is a column on the same row, so you can filter and group across results from different operators in one query. The silver OperatorResult cube keeps each result on its own row, which means combining two operators there takes more than one query.
Conversation Insights populates an operator-derived attribute only for conversations the operator actually ran on. A conversation without a given operator has null for that attribute, so grouping by it can produce a null group representing conversations the operator didn't analyze.
The summary row is written at conversation close
Conversation Insights writes the summary row when a conversation reaches the CLOSED state, approximately 15 minutes after the conversation ends. Operator results that arrive after that, such as results from operators that run when the conversation ends, update the existing row.
This has two consequences:
- In-flight conversations don't appear here. To analyze conversations that are still open, query the silver Conversation cube.
- A result that arrives within 7 days of the summary row being written updates the row when it arrives. A result that arrives later is applied by a daily job, so it can take up to a day to appear. To see every result as soon as it lands, query the silver OperatorResult cube.
The ConversationSummary cube includes the following measures:
| Name | Type | Description |
|---|---|---|
ConversationSummary.Count | number | The count of unique conversations. |
ConversationSummary.ParticipantsSum | number | The total number of participants across the selected conversations. A participant who appears in several conversations is counted once per conversation, so this isn't a count of distinct participants. |
ConversationSummary.ParticipantsAvg | number | The average number of participants per conversation. |
ConversationSummary.ParticipantsMin | number | The smallest number of participants in a single conversation. |
ConversationSummary.ParticipantsMax | number | The largest number of participants in a single conversation. |
ConversationSummary.<Name><Aggregation> | number | Each custom measure you register appears here under the name you chose, followed by an aggregation: Sum, Avg, Min, or Max. The aggregation runs across conversations, using one value per conversation. Conversations where the source operator didn't run return null. You can register up to three custom measures. |
For example, a custom measure registered as LeadScore is queryable as ConversationSummary.LeadScoreSum, ConversationSummary.LeadScoreAvg, ConversationSummary.LeadScoreMin, and ConversationSummary.LeadScoreMax. See Define and use custom fields.
The ConversationSummary cube includes the following dimensions:
| Name | Type | Description |
|---|---|---|
ConversationSummary.ConversationId | string | The unique identifier for the conversation. |
ConversationSummary.ConversationName | string | The name of the conversation. |
ConversationSummary.ConversationStatus | string | The current status of the conversation. |
ConversationSummary.Channels | string | The communication channels used in the conversation, as a comma-separated list. For example, voice,sms. |
ConversationSummary.HasHumanAgent | boolean | Whether at least one human agent took part in the conversation. |
ConversationSummary.HasAIAgent | boolean | Whether at least one AI agent took part in the conversation. |
ConversationSummary.CustomerProfileId | string | The profile identifier for the customer participant. |
ConversationSummary.IntelligenceConfigurationIds | string | The intelligence configurations associated with the conversation. |
ConversationSummary.CreatedDate | time | The date and time when the conversation was created. Use .hour, .day, .week, or .month to group by period. |
ConversationSummary.ClosedDate | time | The date and time when the conversation was closed. Use .hour, .day, .week, or .month to group by period. |
| Sentiment operator | ||
ConversationSummary.Sentiment | string | The latest label from the Sentiment operator: positive, negative, neutral, or mixed. null when the operator didn't run on the conversation. |
| Task Completion operator (public beta) | ||
ConversationSummary.TaskCompletion | string | The latest label from the Task Completion operator (public beta): RESOLVED, UNRESOLVED, ESCALATED, or AGENT_DECLINED. null when the operator didn't run on the conversation. |
| Hallucination Detection operator (public beta) | ||
ConversationSummary.HasHallucination | boolean | Whether the Hallucination Detection operator (public beta) found at least one hallucination: an external_context_conflict or a conversation_context_conflict. A context_gap isn't counted as a hallucination. null when the operator didn't run on the conversation. |
ConversationSummary.HallucinationCount | number | The number of hallucinations the Hallucination Detection operator (public beta) found, counting each distinct combination of conflict type and source once. Two external_context_conflict findings against your knowledge base count as one, so this value can be lower than the operator's own hallucination_count. A context_gap isn't counted as a hallucination. null when the operator didn't run on the conversation. |
ConversationSummary.HasExternalContextConflict | boolean | Whether the Hallucination Detection operator (public beta) found an external_context_conflict: a claim by the agent that contradicts your Enterprise Knowledge, Conversation Memory, or both. Counted as a hallucination. null when the operator didn't run on the conversation. |
ConversationSummary.HasConversationContextConflict | boolean | Whether the Hallucination Detection operator (public beta) found a conversation_context_conflict: a claim by the agent that contradicts something said earlier in the conversation. Counted as a hallucination. null when the operator didn't run on the conversation. |
ConversationSummary.HasContextGap | boolean | Whether the Hallucination Detection operator (public beta) found a context_gap: a claim by the agent that can't be verified against your knowledge, memory, or the conversation. Not counted as a hallucination, so it doesn't set HasHallucination or add to HallucinationCount. null when the operator didn't run on the conversation. |
Participant measures don't count distinct participants
Participant IDs aren't available on this cube, so ParticipantsSum counts participant appearances rather than distinct people. To count distinct participants, query the Conversation cube. ParticipantsAvg is an average, so you can't add the averages of two groups together to get the average of both. Query the combined range directly instead.
ConversationSummary.Channels holds every channel the conversation used. A conversation that started over SMS and moved to voice has the value sms,voice.
Choose a filter operator based on whether you want conversations that included a channel or conversations that used an exact combination:
- Filter with
INto select conversations that used any of the listed channels, alone or alongside others. A filter forsmsmatches both a conversation that used SMS alone and one with the valuesms,voice. - Filter with
EQto select an exact combination, such asvoicefor conversations that used voice alone, orsms,voicefor that exact pairing.
The following filter selects every conversation that included SMS:
1{2"expressions": [3{4"op": "IN",5"field": "ConversationSummary.Channels",6"values": ["sms"]7}8]9}
To see the distribution of channel combinations across your conversations, including which combinations are most common, group by ConversationSummary.Channels.
The Conversation cube contains metadata about conversations captured by Conversation Orchestrator, including details about each participant.
Both this cube and ConversationSummary expose a count of unique conversations, so either one answers "how many conversations?" The difference is what else you can ask alongside it. This cube carries participant attributes, so grouping by ParticipantType or ParticipantId returns a row per participant while the count itself stays distinct. Use this cube when participants are part of the question, and use ConversationSummary when they are not.
The Conversation cube includes the following measures:
| Name | Type | Description |
|---|---|---|
Conversation.Count | number | The count of unique conversations. |
The Conversation cube includes the following dimensions:
| Name | Type | Description |
|---|---|---|
Conversation.ConversationId | string | The unique identifier for the conversation. |
Conversation.ConversationName | string | The name of the conversation. |
Conversation.ConversationStatus | string | The current status of the conversation. |
Conversation.IntelligenceConfigurationIds | string | The intelligence configurations associated with the conversation. |
Conversation.ParticipantId | string | The unique identifier for the participant. |
Conversation.ParticipantType | string | The type of participant (for example, agent or customer). |
Conversation.ParticipantProfileId | string | The profile identifier for the participant. |
Conversation.CreatedDate.hour | time | The date and time when the conversation was created, grouped by hour. Use .day, .week, or .month for other granularities. |
The OperatorResult cube contains results from intelligence operators run on conversations. Use this cube to count and group operator results by operator name, label, channel, or configuration.
The following operators produce results in the OperatorResult cube:
- Twilio-authored operators:
- Sentiment operator, which appears as
OperatorNameSentimentand contributes its label (positive,negative,neutral, ormixed) through theOperatorLabeldimension. - Task Completion operator (public beta), which appears as
OperatorNameAgent-Task-Completionand contributes its label (RESOLVED,UNRESOLVED,ESCALATED, orAGENT_DECLINED) through theOperatorLabeldimension. - Hallucination Detection operator (public beta), which appears as
OperatorNameHallucination-Detectionand contributes each distinct finding as atype:sourcevalue, such asexternal_context_conflict:knowledge, through theDetectedHallucinationandOperatorLabeldimensions. A result with no findings has an empty value.
- Sentiment operator, which appears as
- Custom operators with
outputFormat: JSONthat have a registered custom measure, which contribute that measure's numeric value. - Custom operators with
outputFormat: CLASSIFICATION, which contribute their label through theOperatorNameandOperatorLabeldimensions.
The OperatorResult cube includes the following measures:
| Name | Type | Description |
|---|---|---|
OperatorResult.Count | number | The count of unique operator results. |
OperatorResult.<Name><Aggregation> | number | Each custom measure you register also appears here, at operator result grain rather than conversation grain. |
A custom measure is available on both cubes, with the same Sum, Avg, Min, and Max aggregations. Query it on ConversationSummary, such as ConversationSummary.LeadScoreAvg, to analyze one value per conversation, or on OperatorResult, such as OperatorResult.LeadScoreAvg, to work with the individual results behind it. See Define and use custom fields.
The OperatorResult cube includes the following dimensions:
| Name | Type | Description |
|---|---|---|
OperatorResult.ConversationId | string | The unique identifier for the conversation. |
OperatorResult.IntelligenceConfigurationId | string | The unique identifier for the intelligence configuration. |
OperatorResult.IntelligenceConfigurationName | string | The display name of the intelligence configuration. |
OperatorResult.KnowledgeBaseId | string | The Knowledge Base ID used during operator rule execution. |
OperatorResult.MemoryStoreId | string | The unique identifier for the memory store. |
OperatorResult.OperatorId | string | The unique identifier for the operator. |
OperatorResult.OperatorName | string | The name of the operator (for example, Agent-Task-Completion or Hallucination-Detection). |
OperatorResult.OperatorLabel | string | The label associated with the operator result (for example, positive, RESOLVED, or external_context_conflict:knowledge). |
OperatorResult.ExecutedChannels | string | The communication channel for the conversation (for example, voice, chat, sms, whatsapp). |
OperatorResult.CreatedDate.hour | time | The date and time when the operator result was created, grouped by hour. Use .day, .week, or .month for other granularities. |
| Hallucination Detection operator (public beta) | ||
OperatorResult.DetectedHallucination | string | Each distinct finding the Hallucination Detection operator (public beta) found, as a type:source value such as external_context_conflict:knowledge, or type alone, such as context_gap, when the finding has no source. Empty when the operator found nothing, and null for results from other operators.A result with several findings appears once per finding when you group by this dimension, so the counts across groups can add up to more than the number of results. To exclude other operators, filter with { "op": "NE", "field": "OperatorResult.DetectedHallucination", "values": [null] }. |
Time dimensions group data by time periods. Use dimension names with granularity suffixes.
ConversationSummary cube:
ConversationSummary.CreatedDate.hour: group by hourConversationSummary.CreatedDate.day: group by dayConversationSummary.CreatedDate.week: group by weekConversationSummary.CreatedDate.month: group by month
The same suffixes apply to ConversationSummary.ClosedDate, which is available on this cube only.
Conversation cube:
Conversation.CreatedDate.hour: group by hourConversation.CreatedDate.day: group by dayConversation.CreatedDate.week: group by weekConversation.CreatedDate.month: group by month
OperatorResult cube:
OperatorResult.CreatedDate.hour: group by hourOperatorResult.CreatedDate.day: group by dayOperatorResult.CreatedDate.week: group by weekOperatorResult.CreatedDate.month: group by month
See Query syntax for examples.
Use the Metadata API to retrieve the available cubes, measures, and dimensions:
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID at twilio.com/console5// Provision API Keys at twilio.com/console/runtime/api-keys6// and set the environment variables. See http://twil.io/secure7// For local testing, you can use your Account SID and Auth token8const accountSid = process.env.TWILIO_ACCOUNT_SID;9const apiKey = process.env.TWILIO_API_KEY;10const apiSecret = process.env.TWILIO_API_SECRET;11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });1213async function fetchMetadata() {14const metadata = await client.insights.v3.metadata.fetch();1516console.log(metadata.domain);17}1819fetchMetadata();
The metadata response provides the authoritative list of available data, including descriptions and types.
Explore the following resources to learn more:
- Aggregate conversation data: Run your first queries against the Metadata and Query resources.
- Query syntax: Learn how to construct queries with filters, aggregations, and time granularity.
- Sync to Data Destinations: Send one summary record per conversation to your data warehouse, observability, or analytics tools.