Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI

On this page
Looking for more inspiration?Visit the

Core concepts


(new)

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(link takes you to an external page). 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.

(information)

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.


Cubes

cubes page anchor

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:

LayerCubeDescription
GoldConversationSummaryOne row per conversation, with metadata, participant counts, and operator results such as sentiment, task completion, and hallucinations rolled up into a single record.
SilverConversationConversation metadata from Conversation Orchestrator, including participant details.
SilverOperatorResultResults from intelligence operators run on conversations.

Gold and silver cubes

gold-and-silver-cubes page anchor

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.

(information)

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 questionCubeWhy
How many conversations closed last week?ConversationSummaryOne row per conversation, so the count is a conversation count.
How do conversations with AI agents compare to conversations with human agents?ConversationSummaryHasAIAgent and HasHumanAgent flag the whole conversation.
What share of AI agent conversations were resolved?ConversationSummaryTaskCompletion and HasAIAgent are on the same row.
Which resolved conversations contained a hallucination?ConversationSummaryTaskCompletion and HasHallucination can be filtered together in one query.
How is my own AI agent quality score trending week over week?ConversationSummaryRegister 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?ConversationSummaryCustom measures are available here at one value per conversation.
How do conversation outcomes relate to my CRM or order data?ConversationSummarySync it to your data warehouse and join on ConversationId or CustomerProfileId.
Which operators ran, and what did each one return?OperatorResultEach 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.


ConversationSummary cube

conversationsummary-cube page anchor

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.
(information)

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.

How the summary row is built

how-the-summary-row-is-built page anchor

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.

(warning)

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.

ConversationSummary measures

conversationsummary-measures page anchor

The ConversationSummary cube includes the following measures:

NameTypeDescription
ConversationSummary.CountnumberThe count of unique conversations.
ConversationSummary.ParticipantsSumnumberThe 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.ParticipantsAvgnumberThe average number of participants per conversation.
ConversationSummary.ParticipantsMinnumberThe smallest number of participants in a single conversation.
ConversationSummary.ParticipantsMaxnumberThe largest number of participants in a single conversation.
ConversationSummary.<Name><Aggregation>numberEach 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.

ConversationSummary dimensions

conversationsummary-dimensions page anchor

The ConversationSummary cube includes the following dimensions:

NameTypeDescription
ConversationSummary.ConversationIdstringThe unique identifier for the conversation.
ConversationSummary.ConversationNamestringThe name of the conversation.
ConversationSummary.ConversationStatusstringThe current status of the conversation.
ConversationSummary.ChannelsstringThe communication channels used in the conversation, as a comma-separated list. For example, voice,sms.
ConversationSummary.HasHumanAgentbooleanWhether at least one human agent took part in the conversation.
ConversationSummary.HasAIAgentbooleanWhether at least one AI agent took part in the conversation.
ConversationSummary.CustomerProfileIdstringThe profile identifier for the customer participant.
ConversationSummary.IntelligenceConfigurationIdsstringThe intelligence configurations associated with the conversation.
ConversationSummary.CreatedDatetimeThe date and time when the conversation was created. Use .hour, .day, .week, or .month to group by period.
ConversationSummary.ClosedDatetimeThe date and time when the conversation was closed. Use .hour, .day, .week, or .month to group by period.
Sentiment operator
ConversationSummary.SentimentstringThe 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.TaskCompletionstringThe 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.HasHallucinationbooleanWhether 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.HallucinationCountnumberThe 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.HasExternalContextConflictbooleanWhether 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.HasConversationContextConflictbooleanWhether 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.HasContextGapbooleanWhether 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.
(information)

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.

Filter and group by channel

filter-and-group-by-channel page anchor

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 IN to select conversations that used any of the listed channels, alone or alongside others. A filter for sms matches both a conversation that used SMS alone and one with the value sms,voice.
  • Filter with EQ to select an exact combination, such as voice for conversations that used voice alone, or sms,voice for 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:

NameTypeDescription
Conversation.CountnumberThe count of unique conversations.

The Conversation cube includes the following dimensions:

NameTypeDescription
Conversation.ConversationIdstringThe unique identifier for the conversation.
Conversation.ConversationNamestringThe name of the conversation.
Conversation.ConversationStatusstringThe current status of the conversation.
Conversation.IntelligenceConfigurationIdsstringThe intelligence configurations associated with the conversation.
Conversation.ParticipantIdstringThe unique identifier for the participant.
Conversation.ParticipantTypestringThe type of participant (for example, agent or customer).
Conversation.ParticipantProfileIdstringThe profile identifier for the participant.
Conversation.CreatedDate.hourtimeThe 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 OperatorName Sentiment and contributes its label (positive, negative, neutral, or mixed) through the OperatorLabel dimension.
    • Task Completion operator (public beta), which appears as OperatorName Agent-Task-Completion and contributes its label (RESOLVED, UNRESOLVED, ESCALATED, or AGENT_DECLINED) through the OperatorLabel dimension.
    • Hallucination Detection operator (public beta), which appears as OperatorName Hallucination-Detection and contributes each distinct finding as a type:source value, such as external_context_conflict:knowledge, through the DetectedHallucination and OperatorLabel dimensions. A result with no findings has an empty value.
  • Custom operators with outputFormat: JSON that have a registered custom measure, which contribute that measure's numeric value.
  • Custom operators with outputFormat: CLASSIFICATION, which contribute their label through the OperatorName and OperatorLabel dimensions.

Query Twilio-authored operator results

query-twilio-authored-operator-results page anchor

To get a Twilio-authored operator's results, filter on OperatorResult.OperatorName and group by the dimension that holds its result:

OperatorFilter OperatorName onGroup by
SentimentSentimentOperatorResult.OperatorLabel
Task Completion (public beta)Agent-Task-CompletionOperatorResult.OperatorLabel
Hallucination Detection (public beta)Hallucination-DetectionOperatorResult.DetectedHallucination

For example, the following query counts Task Completion results by label:

Count Task Completion results by labelLink to code sample: Count Task Completion results by label
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID at twilio.com/console
5
// Provision API Keys at twilio.com/console/runtime/api-keys
6
// and set the environment variables. See http://twil.io/secure
7
// For local testing, you can use your Account SID and Auth token
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13
async function createQueryResults() {
14
const query = await client.insights.v3.query.create({
15
domain: "Conversations",
16
query: {
17
measures: ["OperatorResult.Count"],
18
dimensions: ["OperatorResult.OperatorLabel"],
19
filters: [
20
{
21
expressions: [
22
{
23
op: "EQ",
24
field: "OperatorResult.OperatorName",
25
values: ["Agent-Task-Completion"],
26
},
27
{
28
op: "GT",
29
field: "OperatorResult.CreatedDate",
30
values: ["2026-11-01"],
31
},
32
],
33
},
34
],
35
},
36
});
37
38
console.log(query.domain);
39
}
40
41
createQueryResults();

To answer questions about whole conversations, such as how many were resolved without a hallucination, query the ConversationSummary cube instead. It holds each operator's result as its own dimension, so you don't need to filter by operator. For more query examples, see Aggregate the results with Conversation Insights.

The OperatorResult cube includes the following measures:

NameTypeDescription
OperatorResult.CountnumberThe count of unique operator results.
OperatorResult.<Name><Aggregation>numberEach 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.

OperatorResult dimensions

operatorresult-dimensions page anchor

The OperatorResult cube includes the following dimensions:

NameTypeDescription
OperatorResult.ConversationIdstringThe unique identifier for the conversation.
OperatorResult.IntelligenceConfigurationIdstringThe unique identifier for the intelligence configuration.
OperatorResult.IntelligenceConfigurationNamestringThe display name of the intelligence configuration.
OperatorResult.KnowledgeBaseIdstringThe Knowledge Base ID used during operator rule execution.
OperatorResult.MemoryStoreIdstringThe unique identifier for the memory store.
OperatorResult.OperatorIdstringThe unique identifier for the operator.
OperatorResult.OperatorNamestringThe name of the operator (for example, Agent-Task-Completion or Hallucination-Detection).
OperatorResult.OperatorLabelstringThe label associated with the operator result (for example, positive, RESOLVED, or external_context_conflict:knowledge).
OperatorResult.ExecutedChannelsstringThe communication channel for the conversation (for example, voice, chat, sms, whatsapp).
OperatorResult.CreatedDate.hourtimeThe 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.DetectedHallucinationstringEach 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 hour
  • ConversationSummary.CreatedDate.day: group by day
  • ConversationSummary.CreatedDate.week: group by week
  • ConversationSummary.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 hour
  • Conversation.CreatedDate.day: group by day
  • Conversation.CreatedDate.week: group by week
  • Conversation.CreatedDate.month: group by month

OperatorResult cube:

  • OperatorResult.CreatedDate.hour: group by hour
  • OperatorResult.CreatedDate.day: group by day
  • OperatorResult.CreatedDate.week: group by week
  • OperatorResult.CreatedDate.month: group by month

See Query syntax for examples.


Use the Metadata API to retrieve the available cubes, measures, and dimensions:

Retrieve available cubes, measures, and dimensionsLink to code sample: Retrieve available cubes, measures, and dimensions
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID at twilio.com/console
5
// Provision API Keys at twilio.com/console/runtime/api-keys
6
// and set the environment variables. See http://twil.io/secure
7
// For local testing, you can use your Account SID and Auth token
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13
async function fetchMetadata() {
14
const metadata = await client.insights.v3.metadata.fetch();
15
16
console.log(metadata.domain);
17
}
18
19
fetchMetadata();

The metadata response provides the authoritative list of available data, including descriptions and types.


Explore the following resources to learn more: