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.
Header parameters in Requests (Insights Stats API) apply to this endpoint.
Authorization scopes supported:
Scope | Access granted |
---|---|
stats | Entire endpoint |
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 |
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.
|
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:
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.
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" |
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" |
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" |
Depending on input parameters provided, responses to GET /wfm/agent-states
requests contain agent states for the specified time period.
Success response code and parameters in Responses (Insights Stats API) apply to a successful 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: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.