Getting WFM Intervals (Agent and Queue)

You can use GET request to retrieve historical agent and 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/agent-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/agent-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/agent-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/agent-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/agent-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": "agent-queue",
"page": 0,
"total": 1,
"end": "2018-07-12T16:45:00.000Z",
"results": {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "platformAgentId": 472,
            "loggedInTime": 900,
            "agentName": "Autotester Admin",
            "agentWrapUpTime": 0,
            "agentId": "bc59ce30-6731-11e7-9259-cb127bd0d17b",
            "platformQueueId": null,
            "totalAgentHandleTime": 84.989,
            "end": "2018-07-12T19:15:00.000Z",
            "agentQueueIntervalId": "956767eb-3996-5fac-bf49-d7e6c9513332",
            "addParticipantCount": 0,
            "answeredCallCount": 2,
            "readyTime": 814.301,
            "start": "2018-07-12T19:00:00.000Z",
            "transferedCallCount": 0,
            "queueName": null,
            "tenantAgentId": 220,
            "notReadyTime": 85.699,
            "queueId": "bc59ce30-6731-11e7-9259-cb127bd0d17b",
            "agentTalkTime": 86.027,
            "addParticipantHandedOffCount": 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
tenantId The unique identifier of the tenant.
platformAgentId The unique identifier of the platform user.
loggedInTime

The total time in this interval spent by the agent in the logged-in state for all queues. This statistic includes both Ready and Not Ready states.
agentName The first and last name of the agent.
agentWrapUpTime The total wrap-up time used by this agent on this queue.
agentId The unique identifier of the CxEngage agent.
platformQueueId
  • An integer value that third-party Workforce Management (WFM) systems can use to associate with the CxEngage queue. In CxEngage, queues are identified by a UUID, so a second identification number is required for third-party systems that don't use UUIDs.
    		•
    totalAgentHandleTime

    The total time in this interval spent by the agent for the queue handling contacts. This statistic includes talk time, hold time, and wrap-up time.
    end The date and time (in UTC format) when the interval ended.
    agentQueueIntervalId The unique ID given to this specific interval.
    addParticipantCount

    The total Add Participant actions initiated for a given date range. This includes participants added successfully (for example, conferenced or handed over) and unsuccessfully (for example, canceled or rejected add participants).
    answeredCallCount The count of interactions answered by this agent on this queue.
    readyTime

    The total time in this interval spent by the agent in the Ready state for all queues.
    start The date and time (in UTC format) when the interval started.
    transferedCallCount The count of transfers initiated by this agent on this queue.
    queueName The human-readable name of the queue.
    tenantAgentId The unique identifier of the tenant user.
    notReadyTime

    The total time in this interval spent by the agent in the Not Ready state for all queues.
    queueId The queue's unique identifier.
    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)
    addParticipantHandedOffCount

    The total number of times an interaction was handed over to another agent. A hand off occurs when an agent adds another agent or queue as a participant to an interaction. To count as being handed off, the first agent must leave the interaction before the agent who was added as a participant for it.