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).
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 | 2019-12-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 | 2019-12-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, 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:
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
Type | Required | Example |
---|---|---|
String | False | 1234 |
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
Type | Required | Example |
---|---|---|
String | False | ExtendedAway |
Specify a presence to limit the response to include only activities relating to the specified presence state.
Possible values are:
By default, presence activities relating to all presences are included in the response.
Paging parameters in Requests (Insights Stats API) apply to this endpoint.
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" |
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" |
Depending on input parameters provided, responses to GET /agent-activities/presence
requests contain presence activities for the specified time period.
Success response code and parameters in Responses (Insights Stats API) apply to a successful 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: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.