Conversation Aggregate query
Conversation Aggregate queries show a high-level summary of metrics derived from interactions. The query data includes (but is not limited to) common KPIs pertaining to contact center interactions (such as talk time, abandon time, speed of answer, etc) whether it is about agents, queues, etc.
Before diving too deep into the numbers, take a moment to make yourself familiar with the conversation model in Genesys Cloud.
Conversation aggregate query
A conversation aggregate query summarizes overall conversation metrics during a given interval. This is where you get a higher-level view of one or more interactions and not the individual cradle-to-grave style details (the conversation detail record query is the place to go if that's what you're looking for).
The following example shows a simple timeline to illustrate how some common metrics (full list of possible metrics here) fit into the lifecycle of a single interaction.
The syntax of this query conforms to the general template for aggregate queries.
Metric Considerations
Metrics are common performance indicators to capture higher-level concepts within an interaction, such as speed of answer, talk time, wait time, number of interactions offered to a queue, service level, etc.
It is important to note that just because you query for a metric, you may not see any data about it returned to you.
- In some cases, the metric may simply not be pertinent given the rest of your query. For example, if you ask for how many interactions were offered to the "Sales" queue where the user is Mike. "Offer count" is a metric about the queue and so there is no user attributed to that metric. Filtering your query eliminates data from the result set.
- In other cases, there may have been no scenarios that would have produced a metric in that group/interval. For example, if there were no interactions at all during your query interval, then there will be no data returned for answer time, talk time, etc. This is deliberate and the distinction between null/no-data and zero is an important one. In the case of timer data, a value of zero has logical significance--saying there was an answer time of zero would imply agents are picking up the phone instantly. The impact this would make on averages in aggregate would also be significant.
Note: As this query is about conversations and not users, metrics such as time a user spent in a particular status do not apply here. If that is what you're looking for, please check out the user status aggregates query.
Additionally, not all metrics apply to all media types. The following table lists supported media types for each metric. Metrics that are marked as preview may not have been released yet and are subject to change at any time without notice.
Conversation Aggregate Metrics
Metric | Description | Preview | Media types |
Dimension Considerations
Dimensions can be used to group metrics and to filter results. In both cases, you should be aware that not all dimensions apply to all metrics. For instance, nOffered, tAcd, tFlowOut, and tAbandon are metrics for the ACD participant. None of these metrics will have a userId dimension value because userId is a dimension for users/agents. Similarly, tIvr doesn't have a queueId dimension. If you filter by a dimension that only applies to some metrics, you will only get a subset of metrics in the response. If you group by such a dimension, you will still get all metrics, but spread over multiple groups (with one group that captures all cases where the group-by dimension didn't apply).
Dimensions
Dimension | Type | Description | Preview |
Service level
oServiceLevel is a calculated metric that has a numerator and a denominator. The numerator is calculated as tAnswered.Count - nOverSla.Count. The denominator can be calculated in different ways based on various config options:
- Including flow-outs and short abandons:
tAnswered.count + tAbandon.count + tFlowOut.count - Excluding flow-outs:
tAnswered.count + tAbandon.count - Excluding short abandons:
tAnswered.count + tAbandon.count - tShortAbandon.count + tFlowOut.count - Excluding flow-outs and short abandons:
tAnswered.count + tAbandon.count - tShortAbandon.count
Limitations
Granularity must evenly divide the query interval and can be no finer than one minute.
Example query
This query is asking for a few specific metrics (answer time, abandon time, handle time, and a count of outbound connected calls) for all outbound voice interactions between Feb 2, 2017 13:00 and Feb 3, 2017 partitioned into 12 hour sized buckets. The results of this query are then partitioned into subgroups of both which queue the interaction was on as well as which user handled the interaction.
POST
https://api.mypurecloud.com/api/v2/analytics/conversations/aggregates/query
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T13:00:00.000Z",
"granularity": "PT12H",
"groupBy": [
"queueId",
"userId"
],
"metrics": [
"nOutboundConnected",
"tAnswered",
"tAbandon",
"tHandle"
],
"filter": {
"type": "and",
"predicates": [
{
"dimension": "mediaType",
"value": "voice"
},
{
"dimension": "direction",
"value": "outbound"
}
]
}
}Example response
For each tuple of media type, queue, and user, a list of metrics is returned for each interval queried for. Since the original query asked for a full day broken into 12 hour partitions, we see two intervals returned below. Within each, we see metrics for each. Each of these metrics are composed of stats which show how many milliseconds were attributed to that metric. In the first example of tHandle below, we see that the maximum single measure of handle time in that group+interval was 36374 milliseconds. We also see that there were 3 instances of handle time, and the value of all three of those summed up equals 36374. The mean ("average") handle time in this example (sum divided by count) is ~12,125 milliseconds, or approximately 12 seconds.
{
"results": [
{
"group": {
"mediaType": "voice",
"userId": "09efbb9d-85c5-4ebb-bcdf-9a474a643f4a"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 36374,
"count": 3,
"sum": 80565
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "7ad89ce2-9dc0-48b7-8408-a4cc71fe85c4"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tAbandon",
"stats": {
"max": 178673,
"count": 152,
"sum": 27155033
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "5d4b1929-f7b3-4f58-8a75-58d601153c69",
"userId": "c917b4fd-5042-4e54-b8b6-6c537bc7b338"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 46703,
"count": 1,
"sum": 46703
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "111a59c9-919c-402f-85ea-08e458f9c3bd",
"userId": "949f6810-7769-453c-ae97-5368d0b15572"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 2964405373,
"count": 3,
"sum": 2964671642
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"userId": "0eabf9f6-ad97-4daf-8b3e-d46404a0603d"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 368974,
"count": 2,
"sum": 417944
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"userId": "b3af9e35-888f-4126-8bf9-fabf3a4d1e8e"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 1740,
"count": 2,
"sum": 3104
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "7dab03e2-c0f3-4d23-a49f-4a8943b6cab0",
"userId": "949f6810-7769-453c-ae97-5368d0b15572"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 2000,
"count": 1,
"sum": 2000
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "7ad89ce2-9dc0-48b7-8408-a4cc71fe85c4",
"userId": "35796891-6245-4a74-9812-3fb33343f16b"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "nOutboundConnected",
"stats": {
"count": 13
}
},
{
"metric": "tHandle",
"stats": {
"max": 58295573,
"count": 13,
"sum": 62919367
}
},
{
"metric": "tAnswered",
"stats": {
"max": 85690,
"count": 13,
"sum": 160264
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "111a59c9-919c-402f-85ea-08e458f9c3bd",
"userId": "b3af9e35-888f-4126-8bf9-fabf3a4d1e8e"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "tHandle",
"stats": {
"max": 170223,
"count": 2,
"sum": 178519
}
}
]
}
]
},
{
"group": {
"mediaType": "voice",
"queueId": "7c58ebc4-dad8-46ff-9e91-cdecc6b6d03e",
"userId": "3ebc2e52-2eb4-43fd-a7cf-72b3cd9a8d1e"
},
"data": [
{
"interval": "2017-02-02T13:00:00.000Z/2017-02-03T01:00:00.000Z",
"metrics": [
{
"metric": "nOutboundConnected",
"stats": {
"count": 9
}
},
{
"metric": "tHandle",
"stats": {
"max": 419856,
"count": 9,
"sum": 637640
}
},
{
"metric": "tAnswered",
"stats": {
"max": 128009,
"count": 9,
"sum": 249473
}
}
]
}
]
}
]
}