Get WFM agent states

The GET /wfm/agent-states endpoint gets information about agents’ activities, in a format that is optimized for Workforce Management (WFM) integrations. This information combines presence and workload into a single sequence of Agent States for each agent. This is similar to the simplified status displayed in the ContactPad.

In this page

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.api.newvoicemedia.com
USA nam https://nam.api.newvoicemedia.com
APAC apac https://apac.api.newvoicemedia.com
<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 How to authenticate with a Vonage Contact Center (VCC) API.

Headers

Header parameters in Requests (Insights Stats API) apply to this endpoint.

Authorization scopes supported:

Scope	Access granted
`stats`	Entire endpoint

Parameters

The endpoint accepts the following query string parameters:

`start`

Type	Required	Example
Date	True	`2021-09-19T15:42:39.825Z`

The start date and time of the search window. Use ISO 8601 format.

If you plan to poll this endpoint, we recommend that you set start to the value returned in the upTo parameter in the previous request’s response. For more details, see the FAQ page.

`end`

Type	Required	Example
Date	False	`2021-09-19T15:47:39.825Z`

The end date and time of the search window. Use ISO 8601 format. Default is now.

Max request window

{
"message":"Request window size limit exceeded 31 days"
}

`include`

Type	Required	Example
String	False	`Started`

Determines whether to include activities that started, started or ended, or were processed within the specified time period.

The value dictates which values are searched for within the specified time period. Possible values are:

Started. Searches for only agent states that started.
StartedOrEnded. Searches for agent states that started or ended.
Processed. Searches for agent states that started, ended, or were processed. The inclusion of processed time may mean that states that ended before the specified time period are returned.

If you plan to poll this endpoint then we recommend specifying Processed. Using Processed removes the need for any offset and ensures that you receive all data. Note that using the StartedOrEnded or Processed values can result in duplicate items being returned across search windows.

The default value is Started.

`agentId`

Type	Required	Example
String	False	`1234`

Specify an agent ID to limit the response to include only states relating to the specified agent. agentId is the agent ID provided when creating an agent in the Vonage Contact Center (VCC) Admin Portal.

By default all agents are returned.

Paging parameters in Requests (Insights Stats API) apply to this endpoint.

Requests

Request agent states including processed

curl -L -X GET "https://***.api.newvoicemedia.com/stats/wfm/agent-states?start=2021-12-01T14:18:23.857Z&end=2021-12-11T14:18:23.857Z&include=Processed" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Request page 2 of agent states

curl -L -X GET "https://***.api.newvoicemedia.com/stats/wfm/agent-states?start=2021-12-01T14:18:23.857Z&end=2021-12-11T14:18:23.857Z&page=2" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Request agent states for agent 22752

curl -L -X GET "https://***.api.newvoicemedia.com/stats/wfm/agent-states?start=2021-12-01T14:18:23.857Z&end=2021-12-11T14:18:23.857Z&agentId=22752" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Responses

Depending on input parameters provided, responses to GET /wfm/agent-states requests contain agent states for the specified time period.

Successful responses

Success response code and parameters in Responses (Insights Stats API) apply to a successful response.

Example response

{
  "meta": {
    "page": 1,
    "count": 5,
    "pageCount": 1,
    "totalCount": 5
  },
  "items": [
    {
      "agentId": "0001",
      "start": "2021-10-06T18:45:43.782Z",
      "duration": 54977,
      "state": "Away",
      "description": "Break"
    },
    {
      "agentId": "0001",
      "start": "2021-10-06T18:46:38.759Z",
      "duration": 13696,
      "state": "ReadyRFO",
      "description": "Ready (Outbound)"
    },
    {
      "agentId": "0001",
      "start": "2021-10-06T18:46:52.455Z",
      "duration": 49691,
      "state": "Busy",
      "description": "Live"
    },
    {
      "agentId": "0001",
      "start": "2021-10-06T18:47:42.146Z",
      "duration": 31638,
      "state": "Wrap",
      "description": "Live"
    },
    {
      "agentId": "0001",
      "start": "2021-10-06T18:48:13.784Z",
      "duration": null,
      "state": "Ready",
      "description": "Ready"
    }
  ],
  "upTo": "2021-10-06T18:48:35.101Z"
}

Agent states contain the following parameters:

agentId. The agent’s ID, as defined in VCC during agent creation.
start. A time stamp that indicates when the state started. start is a UTC date and time in ISO 8601 format.
duration. A length of time, in milliseconds, that indicates exactly how long the agent remained in this state. If the agent is currently in this state, duration is null.
state. The agent state. The different agent states are:
- Ready. The agent is not working on any interactions, and is capable of receiving new interactions.
- ReadyRFO. The agent is not working on any interactions, and cannot be routed new interactions. This corresponds to an agent presence of Ready (Outbound) or Ready (Offline).
- Away. The agent is temporarily away and is not available to receive new interactions. A state of Away commonly indicates activities such as breaks.
- ExtendedAway. The agent is away for an extended period of time and is not available to receive new interactions. A state of ExtendedAway commonly indicates activities such as meetings or lunch.
- LoggedOut. The agent is logged out of ContactPad, and cannot work on interactions or receive new interactions.
- Busy. The agent is being offered, or is connected to, one or more interactions.
- Wrap. The agent was in the wrap period at the end of one or more interactions. Wrap time is normally used for post interaction work, such as note taking.
- Unexpected. The agent (who was available for work) did not answer their phone, or their line is busy on another call.
- Failed. A Failed activity can occur at any time during an interaction. Possible causes are network congestion, a fault on the line, or configuration issue.
description. If the agent state is Busy, Wrap, Unexpected, or Failed, description contains the type of interaction associated with the state. Possible values are Live, Semi-Live and Non-Live. If the agent state is Ready, ReadyRFO, Away, ExtendedAway, or LoggedOut, description contains the description name of the agent’s presence. For example, a state of ExtendedAway may have a description of Lunch or Meeting.