Data model

Conversation Insights uses a semantic data model based on OLAP (Online Analytical Processing) concepts. This page explains the key concepts and lists the available data you can query.

Core concepts

Cubes

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: conversation metadata from Conversation Orchestrator.
OperatorResult: results from intelligence operators run on conversations.

Measures

Measures are numeric values that can be aggregated. Use measures to count, sum, or calculate statistics across your data.

Example: Conversation.Count returns the count of unique conversations.

Dimensions

Dimensions are attributes that describe your data. Use dimensions to filter results or group measures into categories.

Example: Conversation.ConversationStatus contains the current status of the conversation.

Conversation cube

The Conversation cube contains metadata about conversations captured by Conversation Orchestrator.

Conversation measures

The Conversation cube includes the following measures:

Name	Type	Description
`Conversation.Count`	number	The count of unique conversations.

Conversation dimensions

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.

OperatorResult cube

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.

OperatorResult measures

The OperatorResult cube includes the following measures:

Name	Type	Description
`OperatorResult.Count`	number	The count of unique operator results.

OperatorResult dimensions

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 Knowledge Base linked to the operator result.
`OperatorResult.OperatorId`	string	The unique identifier for the operator.
`OperatorResult.OperatorName`	string	The name of the operator (for example, Sentiment Analysis).
`OperatorResult.OperatorLabel`	string	The label associated with the operator result (for example, positive, negative).
`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.

Time dimensions

Time dimensions group data by time periods. Use dimension names with granularity suffixes.

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.

Discover available data

Use the Metadata API to retrieve the current list of cubes, measures, and dimensions:

Retrieve available cubes, measures, and dimensions

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
8const 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 });
12
13async function fetchMetadata() {
14  const metadata = await client.insights.v3.metadata.fetch();
15
16  console.log(metadata.domain);
17}
18
19fetchMetadata();

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

Next steps

Explore the following resources to learn more:

Aggregate conversation data
Query syntax: learn how to construct queries with filters and aggregations.