Core concepts

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:

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

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

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.

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 value available when the row is written. 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 ConversationSummary cube includes the following 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:

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:

The Conversation cube includes the following dimensions:

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:

• Sentiment operator (Twilio-authored).
• Custom operators with outputFormat: CLASSIFICATION, which contribute their label through the OperatorName and OperatorLabel dimensions.
• Custom operators with outputFormat: JSON that have a registered custom measure, which contribute that measure's numeric value.

The OperatorResult cube includes the following measures:

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:

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:

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:

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