Retrieving agent state statistics
Deprecated API
You must be authenticated to run this method. For information on authentication, see V0 - Authentication API.
All requests to this API are required to be cached by clients for 12 minutes (720 seconds) using the Cache-Control header.
Request Scheme
HTTPS
Request Uri
GET v{v#}/{accountKey}/statistics/agentstates
Request Headers
Authorization (required)
This header requires an OAuth bearer token. For information on the bearer token, see How to use your bearer access token.
Accept (required)
application/json; version=2
Indicates that the media type required from the server is JavaScript Object Notation (JSON). The version parameter is compulsory and you must set it to 2. No other content type is supported.
Parameters
You must provide one of either interval or latest, or both start and end.
start
Defines the start of a range that restricts statistics to a time period. Format is in a specific subset of ISO8601 YYYY-MM-DDThh:mm:ssZ. For example, December 10th 2013 15:00:20 is 2013-12-10T15:00:20Z. You must use the 'Z' suffix to indicate UTC time. The caller must translate local time to UTC. Fractional seconds may be accepted, but sub-second accuracy of filtering should not be expected. The maximum period that you can request in a single call is 25 hours.
end
Defines the start of a range that restricts statistics to a time period. The format matches that required for the start parameter.
interval
Decimal time period (in minutes). Used to retrieve statistics for the past number of minutes. Must be greater than 0 and not
more than 1560 minutes (1 day).
latest
Only supported value is "true". Use this to indicate if you want the past 30 minutes worth of statistics returned
Examples
Most URLs in the example code use the following values:
- ***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL EMEA emea https://emea.newvoicemedia.com USA nam https://nam.newvoicemedia.com APAC apac https://apac.newvoicemedia.com - a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
- <ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.
All agent state statistics for a specified date range
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?start=2014-02-10T15:00:00Z&end=2014-02-11T07:15:00Z" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
All the latest agent state statistics
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
agentstates
?latest=true" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
All the agent state statistics for the past 50 minutes
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
agentstates
?interval=50" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
Example responses
Returns HTTP status code of 200 and a full JSON representation of agents' states for the specified time period:
HTTP/1.1 200 OK
Cache-Control: must-revalidate, max-age=720, private
Content-Type: application/json; charset=utf-8
Vary: Accept,Authorization
{
"count":2,
"stats":[
{
"agentId":"10955",
"groupId":"",
"stateChangedAt":"2014-02-12T15:06:07Z",
"state":"Ready",
"duration":"00:00:09"
},
{
"agentId":"10955",
"groupId":"44311",
"stateChangedAt":"2014-02-12T15:06:16Z",
"state":"Busy Inbound",
"duration":"00:00:12",
"callGuid":"0148e4d3-684f-b8b7-e2ba-9014639797f1"
}]
}
callGuid
is only returned for Busy, Call Transferred and Wrap Up (Auto and Manual) agent states.Example: Invalid requests
Most URLs in the example code use the following values:
- ***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL EMEA emea https://emea.newvoicemedia.com USA nam https://nam.newvoicemedia.com APAC apac https://apac.newvoicemedia.com - a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
- <ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.
Version not specified
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
agentstates
?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"
Returns HTTP status code of 404.
An invalid interval was used
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
agentstates
?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 400, containing a message in a similar format to:
Minute interval supplied exceeds 1 day or is less than 0
An invalid date format was used
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
agentstates
?start=2014-02-10 23:15:00" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 400, containing a message in a similar format to:
{
"message": "The request is invalid."
}
Response values
Property | Description | Additional information |
---|---|---|
agentId | The ID of the agent. | |
groupId | The ID of the group to which the agent belongs. | If the agent does not belong to a group, an empty string will be returned. |
stateChangedAt | The date and time of the agent state change. | This is a UTC value presented in the ISO 8601 format YYYY-MM-DDThh:mm:ssZ. |
state | The agent's state. | For a full list of possible values, see "Valid agent state values" below. |
duration | The time that the agent is in the corresponding state. | This is presented in hh:mm:ss format. |
callGuid | The unique identifier (global) of the interaction. | This data will only be included where an interaction is involved, i.e. for Busy, Call Transferred and Wrap Up (Auto and Manual) agent states. |
Valid agent state values
The following list shows the valid values for state
:
- Away
- Break
- Busy In Return
- Busy Inbound
- Busy Internal
- Busy Out Return
- Busy Outbound
- Busy Payment IVR
- Call Failed IVR
- Call Transferred
- Caller Hangup IVR
- CC
- CCA
- Comfort Break
- Dialling
- Extended Away
- Fault on Line
- In Meeting
- Ivr Transfer Error
- Line Busy
- Logged Out
- Lunch
- Network Congestion
- No Answer
- Paperwork
- Ready
- Ready (Offline)
- Ready for Outbound
- Team Meeting
- Training
- Transfer In
- UnexpectedProhibitedEmergency
- Wrap Up (Auto)
- Wrap Up (Manual)
The following values for state
are also valid if you have set up custom states:
- Custom State 256-271 (custom Wrap Up states)
- Custom State 304-319 (custom Away states)
- Custom State 320-335 (custom Extended Away states)
- Custom State 384-399 (custom Ready for Outbound states)
For information about setting up custom states, see /wiki/spaces/PD/pages/2884021.