Getting Agent States

You can use GET request to retrieve all agent state records within a time range that you specify.

We recommend that you make requests at least every 15 seconds to ensure a consistent and accurate flow of data to your workforce management or business intelligence system.

When events arrive at the RTA service on the CxEngage platform:

  • The events are written as agent state records to the database and are available immediately.
  • The database automatically sorts the agent state records based on their original timestamps.

Server clock drift can occur when specifying the time parameters in a query. If your server's clock is 15 seconds ahead of the CxEngage platform, for example, you may receive events that are out of order.

To avoid server clock drift with the CxEngage platform, sync your server with pool.ntp.org by adding entries to your server's ntp.conf file. Instructions are available at pool.ntp.org.

Before You Begin

Ensure that you have completed the following tasks:

Request

Sample request

The request below gets agent state information on a tenant:

curl GET -u <username:password> -H "Content-Type: application/json" https://api.cxengage.net/v1//tenants/<tenantID>/wfm/rta?start=<startTime>&end=<endTime>&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 agent state data. Note the following:

  • Time range cannot exceed 10 minutes.
  • Agent state data is available for up to three days.
  • The data is always delayed by 15 seconds.

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

In the request, specify start like this:

GET https://api.cxengage.net/v1//wfm/rta?start=2016-01-17T20:15:00Z

end no string

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

  • The time range cannot exceed 10 minutes.

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

  • Avoid requesting data that is younger than 15 seconds. The closer the end is to the current time, the more likely it is that you'll receive event that's out of order.
  •  Specifying end is optional.
    • If start is more than 10 minutes in the past, you must include the end parameter in the request.
    • If start is less than 10 minutes in the past, you can leave end blank. The returned records will be between start and the current time.
    • If you don't specify end, the API call returns all the records from start up to current time.

In the request, specify end like this:

GET https://api.cxengage.net/v1/wfm/rta?start=2016-01-17T20:15:00Z&end=2016-01-17T20:45:00:999Z

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//wfm/rta?start=2016-01-17T20:15:00Z&limit=100

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//wfm/rta?start=2016-01-17T20:15:00Z&limit=100&offset=45

Response parameters

Sample response

The request returns JSON structured like the example below:

"results": [
        {
            "platformAgentId": 15251,
            "eventType": "agent-not-ready",
            "loginTimestamp": "2017-10-06T17:50:59.690Z",
            "nextEventId": "0a903d70-aabf-11e7-b5e2-9a5ac3da6edd",
            "agentName": "Admin Subpub-Admin",
            "sessionId": "e98c1770-aabe-11e7-8aba-0fc9cd50d3ff",
            "capacity": [
                {
                    "channels": {
                        "email": 0,
                        "voice": 0,
                        "workItem": 0,
                        "messaging": 0,
                        "sms": 0
                    },
                    "allocation": "not-allocated",
                    "load": 0,
                    "capacity": 1
                }
            ],
	"transfers": [
		{ 
			"interactionId": "73a63320-cd80-11e8-8178-02d1c7920e75",
			"toAgentId": "f818b240-7d3b-11e7-b08f-6e56a766befb",
			"transferStartTimestamp": "2018-10-11T18:07:11.382Z",
			"transferEndTimestamp": "2018-10-11T18:07:48.188Z" 
		}
		,
		{
			"interactionId": "92d43990-cd80-11e8-8178-02d1c7920e75",
			"toAgentId": "f95725b0-7d3b-11e7-b08f-6e56a766befb",
			"transferStartTimestamp": "2018-10-11T18:08:04.908Z",
			"transferEndTimestamp": "2018-10-11T18:09:18.284Z"
		}
	]
            "agentId": "b6828f70-a38f-11e7-bbe9-0fc9cd50d3ff",
            "presence": "not-ready",
            "end": "2017-10-06T17:51:55.079Z",
            "durationSeconds": 1.779,
            "state": "away",
            "reasonName": "Lunch",
            "reasonListName": "Away Reasons",
            "eventId": "0980a230-aabf-11e7-8aba-0fc9cd50d3ff",
            "reasonListId": "c3e00c20-87ff-11e7-b018-9a5ac3da6edd",
            "reasonId": "f9608f20-87fd-11e7-b018-9a5ac3da6edd",
            "start": "2017-10-06T17:51:53.300Z",
            "tenantAgentId": 9326,
            "allocation": "not-allocated",
            "direction": "inbound"
        }]

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.
timezone string The time zone for which the request was made, for example, UTC.
limit integer The number of records to return from the specified offset.
offset integer The offset from the request.
start string

The date and time, in UTC format, of the start of the time range being requested.
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:

  The following table contains a list of all possible parameters that could be listed for an event.
Parameter Description
platformAgentId The agent's ID on the platform.
eventType

The type of event, which can be one of the following types:

  • agent-session-start
  • agent-capacity
  • agent-ready
  • agent-not-ready
loginTimestamp The date and time (in UTC format) when the agent logged in.
nextEventId The unique identifier of the event that follows this event.
agentName The agent's user name on the CxEngage platform.
sessionId The unique identifier of the session.
capacity

Details about the agent's capacity, including:

  • channels—For each channel that agents can work with, the number of interactions they are currently handling.
  • allocation—The agent’s allocation as either allocated, fully-allocated, or not-allocated
  • load—The agent’s load, which is represented as a decimal. The load is calculated by the number of interactions the agent is handling out of the maximum number of interactions they can handle. For example, if an agent is working with one SMS interaction and can work with a maximum of two concurrently, 0.5 is shown.
  • capacity—The agent’s capacity, which is the maximum number of interactions they can work with concurrently.
transfers

Transfer details including:

  • interactionId—The unique identifier of the interaction.
  • toAgentId—The unique identifier of the user that received the transfer.
  • transferStartTimestamp—The date and time, in UTC, when the transfer was initiated.
  • transferEndTimestamp—The date and time, in UTC, when the transfer was completed.
agentId The agent's unique identifier.
presence

The agent's presence, either ready or not-ready.
end The date and time (in UTC format) when the event ended.
durationSeconds The duration, in seconds, of the event.
state

The agent's state, which can be either:

  • idle
  • away
reasonName The name of the presence reason for the agent's state.
reasonListName The name of the presence reason list that contains the presence reason for the agent's state.
eventId The unique identifier of the event.
reasonListId The unique identifier of the presence reason list that contains the presence reason for the agent's state.
reasonId The unique identifier of the presence reason for the agent's state.
start The date and time (in UTC format) when the event started.
tenantAgentId The agent's ID on the tenant.
allocation

The agent’s allocation as either allocated, fully-allocated, or not-allocated.

direction The direction of voice interactions that the agent is handling, either inbound or outbound.