The GET /agent-activities endpoint gets information about agents’ activities. This information includes the agents’ presence, workload, and interaction activities. Use this endpoint for a full picture of an agent’s activity.

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
DateTrue2019-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 start to the value returned in the upTo parameter in the previous request’s response. For more details, see FAQ (Insights Stats API).

end

TypeRequiredExample
DateFalse2019-12-19T15:47:39.825Z

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

Max request window
Request time windows are limited to 31 days for endpoints. If your request exceeds 31 days, the response will contain a HTTP/1.1 400 status code with the following message:

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


include

TypeRequiredExample
StringFalseStarted

Determines whether to include activities that started, started, 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 activities 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.

type

TypeRequiredExample
StringFalsePresence

Specify an agent activity type to limit the response to include only agent activities of the specified type.

Possible values are:

By default, all types of agent activities are returned.

Pagination

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

Requests

Request agent activities including processed

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

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-activities?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 the input parameters you provide, responses to GET /agent-activities requests can contain interaction activities, presence activities, and workload activities for the specified time period. Some of the properties will be null depending on the type of activity.

Successful responses

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

Example response

{
  "meta": {
    "page": 1,
    "count": 6,
    "pageCount": 1,
    "totalCount": 6
  },
  "items": [
    {
      "agentId": "01",
      "type": "Presence",
      "category": "LoggedOut",
      "name": "Logged Out",
      "eligibleForRouting": false,
      "start": "2019-12-19T15:47:07.077Z",
      "status": null,
      "duration": 9523,
      "reason": null,
      "interaction": null,
      "channel": null,
      "workload": null
    },
    {
      "agentId": "01",
      "type": "Presence",
      "category": "Ready",
      "name": "Ready",
      "eligibleForRouting": true,
      "start": "2019-12-19T15:47:16.600Z",
      "status": null,
      "duration": null,
      "reason": null,
      "interaction": null,
      "channel": null,
      "workload": null
    },
    {
      "agentId": "01",
      "type": "Workload",
      "category": null,
      "name": null,
      "eligibleForRouting": null,
      "start": "2019-12-19T15:47:30.246Z",
      "status": null,
      "duration": 86354,
      "reason": null,
      "interaction": null,
      "channel": null,
      "workload": {
        "calls": 1,
        "semiLive": 0,
        "nonLive": 0
      }
    },
    {
      "agentId": "01",
      "type": "Interaction",
      "category": "Ringing",
      "name": null,
      "eligibleForRouting": null,
      "start": "2019-12-19T15:47:31.289Z",
      "status": "Completed",
      "duration": 4547,
      "reason": null,
      "interaction": {
        "guid": "016f1c6b-9766-498c-9756-30afb0354d5b",
        "medium": "Phone",
        "mediumManager": "VCC",
        "direction": "Inbound"
      },
      "channel": {
        "guid": null
      },
      "workload": null
    },
    {
      "agentId": "01",
      "type": "Interaction",
      "category": "Connected",
      "name": null,
      "eligibleForRouting": null,
      "start": "2019-12-19T15:47:35.836Z",
      "status": "Completed",
      "duration": 80764,
      "reason": null,
      "interaction": {
        "guid": "016f1c6b-9766-498c-9756-30afb0354d5b",
        "medium": "Phone",
        "mediumManager": "VCC",
        "direction": "Inbound"
      },
      "channel": {
        "guid": null
      },
      "workload": null
    },
    {
      "agentId": "01",
      "type": "Interaction",
      "category": "Wrap",
      "name": null,
      "eligibleForRouting": null,
      "start": "2019-12-19T15:48:56.600Z",
      "status": "Completed",
      "duration": 3912,
      "reason": null,
      "interaction": {
        "guid": "016f1c6b-9766-498c-9756-30afb0354d5b",
        "medium": "Phone",
        "mediumManager": "VCC",
        "direction": "Inbound"
      },
      "channel": {
        "guid": null
      },
      "workload": null
    }
  ],
  "upTo": "2019-12-19T15:49:39.389Z"
}

The responses for the three activity types are described below.

Interaction activities

Each agent activity of Interaction type indicates that an agent spent time working on an interaction.

The agent can be engaged in multiple activities on different interactions at the same time but in only one activity for each interaction. For example, the agent could be in a Wrap category for a call, whilst in a Connected category for a case.

Example interaction activity

{
      "agentId": "1005",
      "type": "Interaction",
      "category": "Connected",
      "name": null,
      "eligibleForRouting": null,
      "start": "2019-12-19T10:38:58.017Z",
      "status": "Ongoing",
      "duration": 2078,
      "reason": null,
      "interaction": {
        "guid": "015cd2ff-f696-4458-a6a4-01909f155ac5",
        "medium": "Email",
        "mediumManager": "VCC",
        "direction": "Inbound"
      },
      "channel": {
        "guid": "015cd2ff-f696-4458-a6a4-01909f155ac5"
      },
      "workload": null
}

An agent activity of Interaction type contains the following parameters:

The following properties are not applicable to activities of Interaction type and always contain null:

Presence activities

An agent activity of Presence type indicates the agent’s presence status at a point in time.

The agent can manually set their own presence in ContactPad. 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.

The Insights Stats API records when an agent’s presence goes into a new state and the duration of the state when the state ends.

Example presence activity

{
      "agentId": "1234",
      "type": "Presence",
      "category": "Ready",
      "name": "Ready",
      "eligibleForRouting": true,
      "start": "2019-12-19T19:50:14.851Z",
      "status": null,
      "duration": 120000,
      "reason": null,
      "interaction": null,
      "channel": null,
      "workload": null
}

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

The following properties are not applicable to activities of Presence type and always contain null:

Workload activities

An agent activity of Workload type represents the number of interactions that the agent is working on at that point in time. An agent’s workload is broken down by each type of interaction as follows:

An agent has a single workload state at any one time. When an agent begins or finishes work on an interaction, their previous workload activity ends and a new workload activity begins. For example, if an agent was working on a live interaction (call) they would have a workload activity with "calls": 1. "semiLive": 0 and "nonLive": 0. When they complete that call, their new workload activity would present a workload of "calls": 0, "semiLive": 0 and "nonLive": 0.

If an agent has "semiLive": 2 and "nonLive": 10 interactions and receives a call, their workload activity will be "calls": 1. "semiLive": 0 and "nonLive": 0; the live interaction interrupts the semi-live and non-live interactions and therefore their respective counts are zero. When that call ends, the agent can work on the previous semi- and non-live interactions and the new workload activity would present a workload of "calls": 0, "semiLive": 2 and "nonLive": 10.

Workload activities represent how busy agents are throughout the day. In conjunction with an agent’s presence activity, you can use workload activities to model an agent’s availability. For example, a presence activity of Ready category and a workload activity containing "calls": 0, "semiLive": 0 and "nonLive": 0 indicates that an agent is idle.

A new workload activity will be returned each time an agent either starts or finishes working on an interaction.

Example workload activity

{ "agentId": "0003", "type": "Workload", "category": null, "name": null, "eligibleForRouting": null, "start": "2019-12-19T14:35:18.629Z", "status": null, "duration": null, "reason": null, "interaction": null, "channel": null, "workload": { "calls": 1, "semiLive": 0, "nonLive": 0 } }

The following properties are not applicable to activities of Workload type and always contain null: