Transcripts Aggregate query

Transcripts aggregate queries show a high-level summary of metrics for speech and text analytics data from transcripts during a given interval.

Metrics

Metric	Description	Preview
nTopicCommunications	The topics identified for conversation and topic event
oCustomerSentiment	Score of the sentiment detected for a participant in a conversation
oOverTalkSpeechInstances	The number of instances that customer and agent had over-talked.
oSentimentScore	Overall sentiment score detected for a conversation.
tAgentSpeech	The amount of time, in millisecond, that the agent has talked.
tCustomerSpeech	The amount of time, in millisecond, that the customer has talked.
tOtherAudio	The amount of time, in milliseconds, that represents hold , music and other unaccounted durations.
tOverTalkSpeech	The amount of time, in milliseconds, that customer and agent had over-talked.
tSilence	The amount of time, in milliseconds, that has elapsed without any audio input.
tTotalSpeechAndSilence	The total time taken for the entire speech, including all metrics.

For Voice and Chat interactions, the metrics will be accessible 30 minutes after the end of the interaction. For Message and Email interactions, the metrics will be accessible 72 hours after the latest message in the communication.

Dimensions

Dimension	Type	Description	Preview
addressFrom	String	Represents the value(s) of addressNormalized from fromAddress for the participant.
addressTo	String	Represents the value(s) of addressNormalized from toAddress for the participant.
ani	String	Represents the value(s) of addressNormalized from ANI for the participant.
channel	Enum (external, internal)	Represents if the topic was detected externally/internally.
conversationDuration	Long	The duration of the conversation (in seconds).
conversationId	UUID	The conversation unique identifier.
direction	Enum (inbound, outbound)	The initial direction(s) of the conversation.
divisionId	UUID	Represents the division(s) the participant belongs to.
dnis	String	Represents the value(s) of addressNormalized from DNIS for the participant.
flowId	UUID	Represents the FlowId(s) of the communication.
flowVersion	String	Represents the Flow version(s) of the communication.
handleTime	Long	The total amount of time (in seconds) agents spend on handling the conversation.
mediaType	Enum (Call, Callback, Chat, Email, Message, Voice)	Represents the media type for this conversation.
messageType	Enum (Apple, AppleBusinessChat, Discord, Facebook, Instagram, Line, Open, Other, Signal, Slack, Sms, Telegram, Twitter, WeChat, WebMessaging, Whatsapp)	Represents the message type(s).
queueId	UUID	Represents the QueueId(s) of the communication.
resultsBy	Enum (communication, topicEvent)	Type of the record, can be either communication or topic events.
sentimentIndex	Integer	Index of the sentiment if there are multiple sentiments detected.
teamId	UUID	The teamId of the user.
topicId	UUID	Represents the topic(s) detected in the transcript.
userId	UUID	The guid(s) of the user.
wrapUpCode	String	The wrapup code of the conversation.

Metrics and dimensions that are marked as preview may not have been released yet and are subject to change at any time without notice.

The syntax of this query conforms to the general template for aggregate queries.

When querying for *nTopicCommunications* metric, *the resultsBy filter should always be included in the request.*

ResultsBy	nTopicCommunications
Communication	number of interactions during which topic spotting was run (even when topics were not detected)
TopicEvent	number of participants that handled an interaction when topic spotting was run (even when topics were not detected)

Examples

Example: Query for sentiment score

Request This query is asking for the sentiment score metric (oCustomerSentiment) for all data with media type chat for one specific user on September 23rd 2022. The results are partitioned into one hour sized buckets and grouped by user ID.

POST /api/v2/analytics/transcripts/aggregates/query

{
"interval": "2022-09-23T00:00:00.000Z/2022-09-24T00:00:00.000Z",
"granularity": "PT1H",
"groupBy": [
"userId"
],
"metrics": [
"oCustomerSentiment"
],
"filter": {
"type": "and",
"predicates": [
{
"dimension": "mediaType",
"value": "chat"
},
{
"dimension": "userId",
"value": "00112233-1111-2222-3333-444444444444"
}
]
}
}

Response

The result returns one group for each interval and combination of media type and user ID with matching data. The original query asked for a full day broken into one hour partitions. In the response, there are only two intervals with matching data. Within each, we see the aggregated customer sentiment score with the maximum and minimum score, the sum of all scores, and the count. The average score can be computed based on sum and count.

{
"results": [{
"group": {
"mediaType": "chat",
"userId": "12345678-1111-2222-3333-444444444444"
},
"data": [{
"interval": "2022-09-23T10:00:00.000Z/2022-09-23T11:00:00.000Z",
"metrics": [{
"metric": "oCustomerSentiment",
"stats": {
"max": 98,
"min": -95,
"count": 4,
"countNegative": 1,
"countPositive": 3,
"sum": -82
}
}]
}]
}, {
"group": {
"mediaType": "chat",
"userId": "00112233-1111-2222-3333-444444444444"
},
"data": [{
"interval": "2022-09-23T12:00:00.000Z/2022-09-23T13:00:00.000Z",
"metrics": [{
"metric": "oCustomerSentiment",
"stats": {
"max": 100,
"min": -97,
"count": 14,
"countNegative": 5,
"countPositive": 9,
"sum": 10
}
}]
}]
}]
}

Example: Query for agent speech time

Request This query is asking for the agent speech time (tAgentSpeech) in millisecond.