Getting WFM Intervals (Queue)

You can use GET request to retrieve historical queue data aggregated in 15-minute intervals. You specify the time range from which you want to retrieve the data. For example, you can specify a three-hour range. The historical data within that time frame is then aggregated into 15-minute intervals.

You'll need the WFM_HISTORICAL role permission to perform this request.

Request

Sample request

The request below gets historical WFM intervals:

curl GET -u <username:password> -H "Content-Type: application/json" https://api.cxengage.net/v1/tenants/<tenant-id>/wfm/intervals/queue?start=<start>&end=<end>&page=<page>&limit=<limit>&offset=<offset>

Request parameters

The table below lists the parameters you can include in a request:

Parameter Required? Type Description
username:password yes string

The user name and password of the CxEngage user that you created.

tenantId

 yes UUID The unique identifier of the tenant.
start yes string

The date and time, in UTC format, from which you want to start collecting data. Note the following:

  • Time range cannot exceed 7 days.
  • Time range cannot be within 10 minutes of the current time.
  • The start must be specified in a 15-minute increment. Examples: 22:00, 22:15, 22:30.

  • The start doesn't need to include the digit for milliseconds.

In the request, specify start like this:

GET https://api.cxengage.net/v1/tenants/<tenant-id>/wfm/intervals/queue?start=2016-01-17T20:15:00Z&end=<end>

end no string

The date and time, in UTC format, at which you want to stop collecting data. Note the following:

  • The time range cannot exceed 7 days.
  • Time range cannot be within 10 minutes of the current time.
  • The end must be specified in a 15-minute increment. Examples: 22:00, 22:15, 22:30.

  • The end doesn't need to include the digit for milliseconds.

In the request, specify end like this:

GET https://api.cxengage.net/v1/tenants/<tenant-id>/wfm/intervals/queue?start=2016-01-17T20:15:00Z&end=2016-01-17T24:00Z

limit no string

The number of records to return from the specified offset. For example, you can specify that an API call returns 50 records.

In the request, specify limit like this:

GET https://api.cxengage.net/v1/tenants/<tenant-id>/wfm/intervals/queue?start=2016-01-17T20:15:00Z&end=2016-01-17T24:00Z&limit=50

If you don't specify a limit, the API call returns all records. There is no maximum limit the API call can return.
offset no integer

Which record the API call should start returning records from. This value must be greater than or equal to 0. The default is 0, meaning that the search starts from record 0. For example, to start searching from the 45th agent state record set this parameter as offset=45.

In the request, specify offset like this:

GET https://api.cxengage.net/v1/tenants/<tenant-id>/wfm/intervals/queue?start=2016-01-17T20:15:00Z&end=2016-01-17T24:00Z&limit=50&offset=45

Response parameters

Sample response

The request returns JSON structured like the example below:

{
    "tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
    "limit": 1000,
    "offset": 0,
    "start": "2018-07-12T10:30:00.000Z",
    "type": "queue",
    "page": 0,
    "total": 1,
    "end": "2018-07-12T16:45:00.000Z",
    "results": 
    {
		"maxAbandonedTime": 0,
		"tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
		"wrapUpTime": 0,
		"abandonedCallCount": 0,
		"agentWrapUpTime": 0,
		"platformQueueId": 388,
		"queueEndedCount": 0,
		"queueIntervalId": "606bcc07-bc80-5637-84ef-88270b912b94",
		"queueCallbacksConfirmedCount": 0,
		"queueInteractions": 0,
		"busyTime": null,
		"endTimestamp": "2018-07-12T16:45:00.000Z",
		"maxQueueTime": 0,
		"maxQueueCount": 1,
		"conversationTime": 0,
		"offeredCallCount": 0,
		"avgHandleTime": 0,
		"abandonedTime": 0,
		"abandonedInSlaCount": 0,
		"workOfferCancelledCount": 0,
		"handledCallCount": 0,
		"totalServiceLevelContacts": 0,
		"idleTime": null,
		"answeredCallCount": 0,
		"answeredInSlaCount": 0,
		"availableAgents": 0,
		"startTimestamp": "2018-07-12T10:30:00.000Z",
		"shortAbandonsCount": 0,
		"queueName": "Sales",
		"queueTimeoutCount": 0,
		"avgTimeToAnswer": 0,
		"workRejectedCount": 0,
		"queueTime": 0,
		"sla": 0,
		"answerTime": 0,
		"inServiceLevelContacts": 0,
		"queueId": "e31b2400-1cc2-11e8-a4de-115a5b47684f",
		"holdTime": 0,
		"addParticipantCanceledCount": 0,
		"agentTalkTime": 0,
		"maxAnswerTime": 0
       },...
    ]
}

Response parameters

The response includes the following parameters. The response only includes the attributes that you included in the request.

Parameter Type Description
tenantId UUID The unique identifier of the tenant.
limit integer The number of records to return from the specified offset.
offset integer The offset indicates from which page to return intervals.
start string

The date and time, in UTC format, of the start of the time range being requested.
type string The type of interval, either agent, queue or agent-queue.
page string The page returned. By default, this is the first page which is page 0.
total integer

Total number of records found for the time range specified for the request. If you include the limit parameter in the request, total could be greater than limit.

If total is greater than limit, there are remaining records. To get the remaining records, do the following in the subsequent request:

  • Specify the offset (total - limit)
  • Modify the start and end parameters
end string

The date and time, in UTC format, of the end of the time range being requested.

results object

A JSON object containing the following information:

Parameters that have null values are filtered out of the response.

Parameter Description
maxAbandonedTime The highest time an interaction ongoing before it was abandoned.
tenantId The unique identifier of the tenant.
wrapUpTime

The amount of time that an agent was logged in and spent in a Wrap-Up state during the given 15 minute interval. It's calculated off the end timestamp of the interaction queue record and reported in the interval window in which the agent wrapped up the interaction.

Note: This varies from agentWrapupTime, which is calculated and reported individually within an applicable interval window, not totaled at the end of the interval.
abandonedCallCount The count of interactions that were abandoned.
agentWrapUpTime The total time agents involved in this queue spent in wrap-up.
platformQueueId An integer value that third-party Workforce Management (WFM) systems can use to associate with the CxEngage queue. In CxEngage, queues are identfied by a UUID, so a second identification number is required for third-party systems that don't use UUIDs.
queueEndedCount

The number of interactions that ended and were removed from the queue because of the flow's configuration or due to an error that occurred. It's calculated off the end timestamp of the interaction queue record and reported in the interval window in which the interaction ended.

This count increments the count of queue interactions when initiated over the same queue reported in the interval.

queueIntervalId The unique ID given to the queue for this specific interval.
queueCallbacksConfirmedCount The number of times that an interaction is re-queued once a queue callback request is confirmed by the caller, over the same queue or different. For example, when a caller enters the callback number and submits the request, the interaction is re-enqueued back to the queue and counted. It's calculated off the end timestamp of the interaction queue record, and reported in the interval window in which the interaction was re-enqueued.
queueInteractions The count of interactions involved in this queue.
busyTime The total busy time of agents involved in this queue.
end The date and time (in UTC format) when the interval ended.
maxQueueTime The maximum amount of time that elapsed from when an interaction entered a queue until the work was either accepted by an agent or abandoned for a given date range.
maxQueueCount

The highest number of interactions that were in the queue at one time during the interval.

For example, if at one point during the interval 22 interactions were in the queue and at no other time during that interval the number of interactions waiting at one time exceeded 22, then the Max Queue Count is 22.

conversationTime The length of time, in seconds, between when a conversation starts and ends in an active interaction. This statistic includes Hold time. This metric is calculated off the end timestamp of the interaction queue record and reported in the interval window in which the interaction was handled.
offeredCallCount The count of offered interactions.
avgHandleTime The average handle time of interactions.
abandonedTime The total interaction time to ended in customer abandon.
abandonedInSlaCount The count of interactions abandoned within the assigned SLA (either an assigned custom SLA, or the default one of 20 seconds).
workOfferCancelledCount The number of work offers where either the flow cancels the work offer or the customer abandons before the agents accepts or rejects the interaction. It's calculated off the work offer end timestamp, and reported in the interval window in which the interaction was canceled.
handledCallCount

The count of interaction segments that were completed in the interval.

  • This count may include interactions that were received and answered before the interval start time. It includes any calls handled by ending, including wrap up where applicable, in the defined interval. This also includes completed queue callbacks where the callback resulted in conversation time.
  • In the event that an interaction contains multiple segments that were completed within the defined interval, in the same queue being checked, each of those segments would be included in the count. For example, if a call was answered by an agent in Queue A and then transferred to another agent in Queue A who ended the interaction within the defined interval, the count would show 2.
totalServiceLevelContacts

The count of interactions that were accepted by an agent or abandoned by the customer. For an abandoned interaction to be counted in this statistic, the abandon-time must be greater than the abandonThreshold parameter for default or custom SLAs with an abandonType of ignore-abandons.
idleTime The total idle time of agents involved in this queue.
answeredCallCount The count of answered interactions.
answeredInSlaCount The count of interactions answered within SLA (20 seconds for default, or the value for slaThreshold for custom SLAs).
availableAgents The count of online agents that could handle work from this queue.
start The date and time (in UTC format) when the interval started.
shortAbandonsCount The count of interactions abandoned with 5 second of initialization.
queueName The human-readable name of the queue.
queueTimeoutCount

The number of interactions that were removed from the queue because of a queue timeout configured in the flow that received the interaction, within a given interval. It's calculated off the end timestamp of the interaction queue record and reported in the interval window in which the interactions were removed.

This count increments the count of queue interactions when initiated over the same queue reported in the interval.

avgTimeToAnswer The average time to answer interactions, including queue callback work offers.
workRejectedCount The number of work offers sent to an agent that were rejected during the given period of time. It's calculated off the work offer end timestamp, and reported in the interval window in which the interaction was rejected.
queueTime The total time interactions spent in queue.
sla The SLA score for the given queue based on interactions that completed in the given interval. This is calculated using whatever SLA is assigned, either a custom SLA or the default one.
answerTime

The amount of time that elapsed from when a customer entered a queue to when they started an active conversation with an agent.
inServiceLevelContacts

The count of interactions that got answered within the defined SLA for this interval, whether a custom SLA or the default one.

The count of interactions that got answered within the configured slaThreshold for this interval.
queueId The queue's unique identifier.
holdTime The length of time that an agent, who isn't in internal consult, has a customer on hold. In other words, this statistic is measured when there is only one agent interacting with the customer and the agent places that customer on hold.
addParticipantCanceledCount

The number of times that an agent canceled an Add Participant action before another agent accepted the interaction, within the given interval. It's calculated off the end timestamp of the interaction queue record and reported in the interval window in which the initiating agent canceled the Add Participant request.

This count increments the count of queue interactions when initiated over the same queue reported in the interval.

agentTalkTime The length of time that the agent spent talking to a customer. This statistic doesn't include hold time. This expression formats Agent Talk Time in days, hours, minutes, and seconds (d:hh:mm:ss).
maxAnswerTime The maximum amount of time that elapsed from when an interaction entered a queue until the work was accepted by an agent for a given date range.