Skip to contentSkip to navigationSkip to topbar
On this page

Flex Insights Data Model


(warning)

Public beta

Flex Insights (also known as Historical Reporting) is currently available as a public beta release and the information contained in the Flex Insights documentation is subject to change. This means that 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 a Twilio SLA.

Any reference to "Historical Reporting," "Flex Insights API," "Flex Insights Historical Reporting," or "Flex Insights Historical Reporting API" in the Flex Insights documentation refers to Flex Insights.

The Flex Insights Data Model represents the structure and relationships between contact center entities. The model is designed for the analytical needs of the contact center. You can drill down from high-level KPIs calculated on top of the model to individual conversations and agents.

The model is highly optimized for maximum query performance and therefore has certain limitations. Notably, M:N relationships are not present. The model is also heavily denormalized.


Overview

overview page anchor

The Flex Insights Data Models consists of data sets. Each data set, or group of data objects, represents a business entity in the contact center. Data sets are connected to each other based on their real-world relationships.

The following entity-relationship diagram maps how data sets within the model can be viewed with a real-world perspective:

Real-World Relationships of Data Sets.

Each data set contains one or more of the following data objects:

  • Date Dimensions: values that represent the date (or the date and time) that specific events occurred. You can use date dimensions to filter and segment data. For more information, see the Date Dimensions section.
  • Attributes: values that represent a single quality that describes or relates to the data set to which it belongs. Attributes can have text or numeric values. You can use attributes to filter and segment data.
  • Facts (formerly known as Measures): KPIs and other metrics that represent mathematical calculations or aggregations. Facts are calculated as sums, averages, etc., or counts of distinct values. Facts can be segmented by attributes or dates.
(warning)

Warning

Before you begin working with Facts and Attributes, review the Flex Insights Data Model Caveats.

Additionally, the Flex Insights Data Model comes with pre-defined Metrics(link takes you to an external page). Metrics are formulas built on top of facts (fka. measures). The data model may change over time, and pre-defined metrics provide an abstraction from these changes - so try to use pre-defined metrics whenever possible.


This section defines the model's main data sets and lists corresponding data objects. Please note that some data sets do not contain data by default and require custom data integration.

You can view the complete list of data sets by selecting the Manage(link takes you to an external page) tab in the Analytics Portal.

Conversations

conversations page anchor

Conversations represent interactions between agents and customers. Each row in the Conversations data set represents a single Segment that is a part of a conversation or an agent activity (agent status data). These data enable the representation of all of the steps a customer went through when having a conversation with the contact center. You can also correlate these data with agent status data for reporting.

This data set contains data from TaskRouter events.

Attributes

attributes page anchor

This data set includes the following attributes:

Field Name in ReportingBusiness/Reporting DefinitionPopulated by default?Possible Values
Segment (Label ID) (PK)The lowest level of granularity in Insights conversation data. It represents an individual segment within the conversation.Y
Segment (Label External ID)Task SID for segments related to tasks in TaskRouter.Y
AbandonedAbandoned calls are those where the talking party did not reach the intended party.YYes, No
Abandoned PhaseIn inbound segments, this is the phase in which the customer gave up waiting for your agents. In outbound, this is the phase in which the agent stopped trying to reach the customer.YDefault: Queue

Custom values: Short Queue, Ringing, Voicemail, Callback Request.
ActivityThe kind of activity that is performed by an agent. This attribute is only relevant for segments with Kind = Agent Status.YAvailable, Idle, Break, etc.
CampaignA campaign related to this conversation.N
CaseThe case that this segment belongs to. A case is a set of conversations (and the segments they contain) that are related to one issue, inquiry, or sale.N
Communication ChannelThe communication channel used between the customer and the agent.YCall, Chat, SMS, custom, etc.
ContentThe summary of the content of the conversation. The content is reserved for automatic extraction from the monitored communications and it differs by channel, platform features, and customer preferences. For SMS messages it can be the message itself; for emails it can be the subject or an extract from the body; for chat it can be the first few messages; for calls it can be topics. The maximum length of content may be shortened to about 100 characters.N
ConversationThe conversation to which this segment belongs. A conversation is a set of segments related to handling one customer.Y
Conversation Attribute 1Text custom fieldYMoved for Queue Segments in which customers were moved to a different queue

Timeout for Queue Segments from which customers were removed because of a timeout
Conversation Attribute 2Text custom fieldN
Conversation Attribute 3Text custom fieldN
Conversation Attribute 4Text custom fieldN
Conversation Attribute 5Text custom fieldN
Conversation Attribute 6Text custom fieldN
Conversation Attribute 7Text custom fieldN
Conversation Attribute 8Text custom fieldN
Conversation Attribute 9Text custom fieldN
Conversation Attribute 10Text custom fieldN
DestinationThe queue into which the customer went after this segment. Currently empty.N
DirectionThe direction of the conversation. The direction depends on the first segment.YInbound, Outbound, Internal, External, Unknown
External ContactThe contact address the customer used to reach you or the contact address from which you have reached them. This may be an inbound support phone number, your support email, or a phone number that appears on the customer's phone when you call them.Y
Followed ByReferences the segment, if any, that follows this segment within the conversation. This can indicate, for example, a transfer of a customer conversation to another agent.N
Handling Department (Label ID)The department ID for the agent when they handled the conversation.Y
Handling Department (Label Name)The department name for the agent when they handled the conversation.Y
Handling Department (Label Name in Hierarchy)The department name in hierarchy for the agent when they handled the conversation.Y
Handling Team (Label ID)The team ID for the agent when they handled the conversation.Y
Handling Team (Label Team Name)The team name for the agent when they handled the conversation.Y
Handling Team (Label Name in Hierarchy)The team name in hierarchy for the agent when they handled the conversation.Y
Hang Up ByThe party that hung up or left the conversation first.YDefault: Unknown

Custom values available with the Hang Up By plugin(link takes you to an external page): Agent, Customer, Cold Transfer, External Warm Transfer
In Business HoursIndicates whether the conversation happened during the business hours of the contact center.N
Initiated ByIndicates who or what initiated the conversation.N
InitiativeThe highest level of grouping of conversations, intended for representing high-level business initiatives of the company.N
IVR PathThe sequence of options, if any, that the customer selected in your IVR. You may use this to understand what customers wanted to do and whether they were successful, whether they needed to talk to your agents or they gave up.N
KindThe kind of activity or segment.YConversation, Queue, Agent Status, Missed Conversation, Rejected Conversation, Revoked Conversation
LanguageThe language used by the participants in the conversation.N
OutcomeA custom categorization of conversations by how they ended. Exact options depend on each contact center. For example, you can mark conversations that ended up with a sale, that need follow up, or in which the customer asked to unsubscribe from your services.YTask's Reason. Fallback to TaskCompletedReason or TaskCanceledReason.
Preceded ByReferences the segment, if any, that preceded this segment within the conversation. This can indicate, for example, a transfer of a customer conversation from another agent.N
ProductiveCan be used to indicate whether a Conversation is productive or not.NYes/No
QueueThe queue in which the customer was waiting before reaching the agent.Y
Segment (Label Segment Link)The recording URL, if captured, to play back the conversation.N
Segment OrderThe order in which this segment occurred within the conversation. Applies to Kind: Conversation, only.YInteger values in order of segment creation (1,2,3...)
Service LevelThe service level associated with the conversation. Enables you to identify the time-in-queue service level targeted for this conversation.N
SourceThe queue in where the customer was before this segment. Currently empty.N
VirtualIndicates whether the segment should be included in general reports. If Virtual is Yes then these Segments have a special purpose and should not appear in reporting on top of conversations. This is only set to No when the Kind = Conversation. It is set to Yes for all other Kinds.YYes, No
WorkflowThe name of the Workflow that controlled how the segment of the conversation was routed. Typically this workflow decides into which queues and under which circumstances the incoming conversations go, how they are ordered, what happens when a customer waits for too long, etc.Y

This data set includes the following facts:

Field Name in ReportingBusiness/Reporting DefinitionPopulated by default?Possible Values
Abandon TimeThe time after which the call was abandoned without the parties connecting to each other.YInteger
Activity TimeThe time spent in this activity.YInteger
Agent Talk TimeThe time the agent spent talking in the segment.NInteger
Average Response TimeThe time it took agents on average to respond to the customers from the moment the customer contacted the contact center. Currently empty.NInteger
Conversation Measure 1Numeric Custom FieldNInteger
Conversation Measure 2Numeric Custom FieldNInteger
Conversation Measure 3Numeric Custom FieldNInteger
Conversation Measure 4Numeric Custom FieldNInteger
Conversation Measure 5Numeric Custom FieldNInteger
Conversation Measure 6Numeric Custom FieldNInteger
Conversation Measure 7Numeric Custom FieldNInteger
Conversation Measure 8Numeric Custom FieldNInteger
Conversation Measure 9Numeric Custom FieldNInteger
Conversation Measure 10Numeric Custom FieldNInteger
Crosstalk TimeThe time the customer and the agent were talking simultaneously in the segment.NInteger
Customer Talk TimeThe time the customer spent talking in the segment.NInteger
First Response TimeThe time it took to respond to a first customer message from the moment the customer contacted the contact center. Currently empty.NInteger
Focus TimeThe time the agent was focused on handling the conversation. Currently empty.NInteger
Hold TimeThe time the customer spent on hold during this segment.YInteger
IVR TimeThe time the customer spent in the IVR before this segment.NInteger
Longest Silence before AgentThe longest period of silence in a segment before an agent started to talk. May indicate issues like knowledge gaps, inability to keep customers informed during longer tasks, etc.NInteger
Longest Silence before CustomerThe longest period of silence in a segment before a customer started to talk. May indicate dissatisfaction of a customer or agent's inability to assist the customer.NInteger
Longest Talk by AgentThe longest period of continuous talk by an agent. May indicate agents describing a complex problem or failing to explain something plainly and clearly.NInteger
Longest Talk by CustomerThe longest period of continuous talk by a customer. May indicate customers describing a complex problem.NInteger
PriorityThe priority of the conversation. Currently empty.NInteger
Queue TimeThe time the customer spends in a queue before this segment.YInteger
Ring TimeThe time that a ringtone is heard by the customer.NInteger
Silence TimeThe time both the agent and the customer were silent in the segment.NInteger
Talk TimeThe time customer spent talking with an agent. This includes all silences and can be thought of as the time between answering the phone and hanging up.YInteger
Time in SecondsThe time in seconds for the start of a segment/activity.YInteger
Wrap Up TimeThe time an agent spent wrapping up after the call with a customer.YInteger
(information)

Info

Attributes not populated by default are fully customizable. Possible values are listed as recommendations and are shown in order to make sense of the attribute's meaning, or because they are used by existent metrics.

(information)

Info

By default, Flex Insights does not capture IVR Time. In order to surface the IVR metric, you'll need to pass the value through TaskRouter events.

Agents handle conversations with customers. This data set enables you to segment and filter conversations by the agents who handled them.

This data set contains data from TaskRouter worker attributes. Check this resource to learn more about how worker data can be populated into Insights.

This data set includes the following attributes:

  • Agent Attribute 1 , Agent Attribute 2 and Agent Attribute 3: Custom agent attributes.
  • Agent ID (Primary Key - PK): An identifier assigned by contact center management to uniquely identify the agent.
  • Date - Joined: The date when the agent joined the company. Available in Flex Insights when you provide values via custom task attributes .
  • Date - Left: The date when the agent left the company. Available in Flex Insights when you provide values via custom task attributes .
  • Department : A set of Teams. This is a higher-level organization unit than a Team.
  • Email: The agent's email address.
  • First Name: The agent's first name.
  • Last Name: The agent's last name.
  • Location: The agent's physical location.
  • Manager: The agent's manager. This is a single person who is responsible for the agent.
  • Phone : The agent's phone.
  • Role: The agent's role. It enables the segmentation of agents by their role in the company.
  • State: The current state of the agent. It indicates whether they still work in the contact center. Possible values: Active, Inactive.
  • Team: The agent's Team.

Workload breaks down conversations and agent activity (agent status data) into 15-minute intervals. This data set enables accurate intraday workload reporting.

This data set includes the following attributes:

  • Activity: The agent status the agent was in during the 15-minute interval.
  • Order: The order of this workload item within the segment.
  • Workload Kind: The kind of the original segment related to this workload. Refer to "Workload Kind" in Workload Reporting for a list of possible values.

This data set includes the following facts:

  • Activity Time: The time the agent spent in the agent status during the 15-minute interval.
  • Parallel Conversations: The number of conversations the agent was engaged in (including wrap up) while being in the associated agent status during the 15-minute interval.
  • Talk Time: The time the agent spent in talk time for the associated segment during the 15-minute interval.
  • Wrap Up Time: The time the agent spent in wrap up for the associated segment during the 15-minute interval.

Customers are people who contacted the center or were contacted by the center. This data set enables you to segment and filter conversations by demographic attributes.

This data set contains data that TaskRouter provides, together with a customer phone number.

This data set includes the following attributes:

  • Customer (PK): A reference to a single customer. Depending on how well Insights is able to connect individual contact information with a specific customer, one person may appear in several customer records. For example, if Insights is unable to associate a person's phone number and email address, they will appear in two records.
  • Acquisition Date: The date when the customer was acquired.
  • Area: The geographical area where the customer is located.
  • Category: An attribute enabling custom slicing of customer data by category.
  • Country: The country where the customer is located.
  • Customer Attribute 1 , Customer Attribute 2 and Customer Attribute 3: Custom customer fields.
  • Email: The customer's primary email.
  • Gender: The gender of the customer. Possible values: Female, Male, Other, Unknown.
  • Geo Location: GPS coordinates of a representative city or location within the area.
  • Name: The full name of the customer. Includes the first name and the last name if they are available.
  • Organization: The organization to which the customer belongs.
  • Phone: The customer's primary phone number.
  • Region: A higher-level geographical unit than Country. It allows the grouping of countries into regions. There is no required set of regions. Each Flex customer may implement their own segmentation of the world.
  • Type: An indicator that distinguishes between actual customers and agents that are identified as the "customer" in a conversation (in case of internal agent-to-agent segments). See the Flex Insights Data Model Caveats .
  • Year of Birth: The date of birth of the customer.

This data set includes the following facts:

  • Acquisition Cost: The cost of acquiring the customer.
  • Business Value: A positive or negative value expressing how the company values the customer in terms of future possible income or a similar metric.

Supervisors are people that provide feedback to agents using Assessments. This data set enables you to understand how feedback influences performance. Agents that provided feedback to other agents or assessed their conversations also appear in the Supervisors data set.

By default, this data set contains the data of the contacts who made assessments.

This data set includes the following attributes:

  • Supervisor (PK): A Supervisor is anyone who provided feedback on a conversation or an agent, including agents themselves.
  • Department: The supervisor's department, which is a set of Teams.
  • Email: The supervisor's email address.
  • Manager: The supervisor's manager.
  • Role: The supervisor's role, such as the job title or role indicating their permissions.
  • State: The current state of the supervisor. It indicates whether they still work in the contact center.
  • Team: The supervisor's team.

Assessments enable you to categorize conversations, attach comments, and score conversation quality. This data set enhances understanding of different, measurable quality aspects of conversations.

This data set contains manual entries that come from filled conversation questionnaires and comments in Flex Insights.

This data set includes the following attributes:

  • Assessment (PK): A distinct assessment of a conversation quality, given for a question by an assessor.
  • Answer : The answer selected from the range of available answers for the given question.
  • Assessment Type: A reference to the Conversation Screen from which the assessment originated. Possible values: Quality ( Assess feature), Comment ( Comment feature).
  • Category: The category of the metric. Enables the grouping of metrics into categories for reporting on a higher level.
  • Comment: A free-form comment that a supervisor may attach to the assessment.
  • Metric: The assessed question in a questionnaire.
  • Rejection: [Not in use] The reason why the assessment was rejected. The person who was supposed to asses the question declined to asses it, as it was not relevant or was impossible to assess.
  • Report: This indicates whether the assessment should appear in reports. Enables excluding an assessment from reports if, for example, it is a training score or other assessment that should not influence an agent's performance rating. Possible values: Yes, No. If the conversation was assessed but then the assessor removed their scores, the assessments Report flag will be set to No.
  • Review: [Not in use] A reference to the review during which the assessment was done. Enables grouping of assessments into logical units.

This data set includes the following facts:

  • Assessed End Position: The end offset in the segment related to the assessment.
  • Assessed Position: The offset in the segment related to the assessment.
  • Max Score: The maximum possible score of the metric. Equal to 1 for percentages.
  • Min Score: The minimum possible score of the metric. Equal to 0 for percentages.
  • Score: The score in the metric original scoring scale, as defined by the Min Score and Max Score bounds. It may also be outside of these bounds for bonus points and extra negative points.
  • Score Percentage: The score, when normalized to a percentage.
  • Time - Assessment in Seconds: The duration of the content that was the focus of the assessment, expressed in seconds.
  • Weight: The weight of the metric, as set up in the external system. Enables reporting on different metrics that have different importance to an overall score.

This section provides descriptions for date dimensions that are present in the model. Usually, the primary date dimension is the right dimension to use. Use other dimensions for reporting needs that are focused on specific business processes. All dates have a set of attributes that you can use to display data from several different temporal perspectives. All dates are in the Gregorian civil calendar(link takes you to an external page).

The model includes the following date dimensions:

  • Date: The primary date and time used by the majority of events. The date and time when a segment started.
  • Date - Assessment: The date and time when an individual assessment was performed.
  • Date - Joined: The date when an agent joined the company (available in Flex Insights when you provide values via custom task attributes ).
  • Date - Left: The date when an agent left the company (available in Flex Insights when you provide values via custom task attributes ).
  • Date - Workload: The date that is used for intraday workload reporting . This date dimension enables reporting on exactly how much time agents spend in each agent status and conversations in every 15-minute interval.

Date and Date - Assessment date dimensions also have a time dimension that represents the time in minutes that is associated with the start of a segment. You can use the following attributes to understand intraday facts:

  • Hour, Hour - Assessment: The hour of the day for the event in the range from 0 to 23, respectively from 0 AM to 11 PM (you can select a different label to represent time according to your preference).

    Hour interval.
  • Interval 30 Minutes, Interval 30 Minutes - Assessment: The 30-minute interval in which an event happened.
  • Interval 15 Minutes, Interval 15 Minutes - Assessment: The 15-minute interval in which an event happened. The interval is based on the segment/activity start time. For example, conversations starting between 01:15 PM and 01:30 PM are in the interval named 01:15 PM.

    15 min intervals.
  • Time, Time - Assessment: The time in hours and minutes when the event happened. It represents the finest granularity of a time dimension.

Segments, Conversations, Cases, Campaigns, Projects and Initiatives form a hierarchical structure of conversations between your agents and your customers. These attributes enable different levels of analysis:

  • Segment: An atom of any conversation. A segment represents an interval in time dedicated to certain phases during a Conversation.
  • Conversation: A communication between one customer and all agents in the contact center handling them. A conversation is composed of one or more Segments.
  • Case: Multiple conversations regarding the same issue or topic.
  • Project: Multiple cases related to the same project.
  • Campaign: A business goal-oriented communication campaign with a set of customers. This might be an outbound sales campaign, marketing campaign leading to inbound conversations, social media content publishing, etc.
  • Initiative: The highest level of grouping of conversations, intended for representing high-level business initiatives of the company.

Flex Insights groups segments into a conversation based on a conversation identifier extracted from TaskRouter event attributes. Flex Insights uses exact matching of IDs with heuristics that attempt to group segments with the same customer within a short period of time into a single conversation. The exact behavior depends on the conversation channel(s) and can be customized by supplying a custom conversation ID as a task attribute, as described here.

(information)

Info

As Segments represent the elementary item in the Conversations data set, all items that reference the Conversations data set are actually tied to a specific segment, even when they actually have Conversation-wide meaning.


Need some help?

Terms of service

Copyright © 2024 Twilio Inc.