Get agent presence activities

The GET /agent-activities/presence endpoint gets information about agents’ presence. Using this endpoint you can determine exactly how long an agent was available for work, at meetings or logged out.

The agent can manually set their own presence in ContactPad. Vonage Contact Center (VCC) can also set the agent’s presence automatically at the end of an interaction. For example, if the agent has set their intended state to Away, VCC sets their presence to Away as soon as their current interaction ends.

An agent only has a single presence at any time. Entering a new presence ends their current presence.

Each presence activity is returned as a period of time, defined by a start date and a duration (if the activity has completed).

Headers

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

Authorization scopes supported:

Parameters

The endpoint accepts the following query string parameters:

start

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

end

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

include

Determines whether to include activities that started, activities that started or ended, or activities that 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 activities that started.
• StartedOrEnded. Searches for agent activities that started or ended.
• Processed. Searches for agent activities that started, ended, or were processed. The inclusion of processed time may mean that activities completed before the specified time period will be 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, using the StartedOrEnded or Processed values can result in duplicate items being returned across search windows.

The default value is Started.

Notes

When polling the API using include parameter StartedOrEnded or Processed will result in duplicate entries being returned across search windows.

agentId

Specify an agent ID to limit the response to include only presence activities relating to the specified agent. agentId is the agent ID provided when creating an agent in the VCC Admin Portal.

By default all agents are returned.

presence

Specify a presence to limit the response to include only activities relating to the specified presence state.

Possible values are:

• Ready
• Away
• ExtendedAway
• LoggedOut

By default, presence activities relating to all presences are included in the response.

Pagination

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

Requests

Request agent activities presences including processed

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-activities/presence?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 activities presences 

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-activities/presence?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"

Responses

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

Successful response

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

Example response

{
"meta": {
  "page": 1,
  "count": 1,
  "pageCount": 1,
  "totalCount": 1
},
"items": [
  {
	"agentId": "1234",
	"start": "2019-12-19T14:03:12.832Z",
	"duration": 9953,
	"name": "Ready",
	"description": "Ready",
	"eligibleForRouting": true
  }
],
"upTo": "2019-12-19T14:05:00.585Z"
}

Presence activities contain the following parameters:

• agentId. The agent’s ID, as defined in VCC during agent creation.
• start. A time stamp that indicates when the presence started. start is a UTC date in ISO 8601format.
• duration. A length of time, in milliseconds, that indicates exactly how long the agent remained in this presence activity. If the agent is currently in this presence, duration is null.
• name. The name of the presence. name is the same as category on the root GET /agent-activities endpoint. The different presence names are:
  • Ready. The agent is working and capable of receiving new interactions. You can determine an agent’s availability based on this presence and the agent’s workload.
  • Away. The agent is temporarily away and is not available to receive new interactions. A presence 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 presence 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.
• description. Presences might also have description names. For example, a presence with the name ExtendedAway may have a description of Lunch or Meeting. description is the same as name on the root GET /agent-activities endpoint.
• eligibleForRouting. A boolean value which indicates whether new interactions can be routed to an agent whilst they are in this presence.

Manual wrap activity types are only reported if used to extend an automatic wrap.