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.

Headers

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

Authorization scopes supported:

ScopeAccess granted
statsEntire endpoint

Parameters

The endpoint accepts the following query string parameters:

start

TypeRequiredExample
DateTrue2021-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

TypeRequiredExample
DateFalse2021-09-19T15:47:39.825Z

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


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

include

TypeRequiredExample
StringFalseStarted

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:

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

TypeRequiredExample
StringFalse1234

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.

Pagination

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: