Get agent activities

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:

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.

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

include

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:

• 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 are 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.

agentId

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

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

Possible values are:

• Presence. The response includes only agent presence activities.
• Interaction. The response includes only agent interaction activities.
• Workload. The response includes only agent workload activities.

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 response 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 only in 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:

• agentId. The agent’s ID, as defined in VCC during agent creation.
• type. The type of activity. type will always be Interaction for an interaction activity.
• category. The category of interaction activity. The following interaction activity categories exist:
  • Ringing. The agent was offered the interaction. For a phone call, the Ringing category describes the period in which the phone was ringing.
  • Connected. The agent was connected to the interaction. Typically the Connected category describes the period the agent was working on the interaction; for a phone call Connected is the period in which parties are connected and able to talk.
    If an agent parks a phone call, the Connected activity ends. A new Connected activity starts when the agent unparks the call.
    If a non-call interaction is interrupted by a call, the Connected activity ends. A new Connected activity starts when the interaction is resumed.
  • Wrap. The agent was in the wrap period at the end of an interaction. Wrap time is normally used for post interaction work, such as note taking.
  • Unexpected. An activity of Unexpected category usually occurs after the Ringing category. The category indicates that an agent (who was available for work) does not answer their phone, or their line is busy on another call.
  • Failed. A Failed activity can occur at any time during an interaction. Possible causes are network congestion, a fault on the line, or configuration issue.
• start. A time stamp that indicates when the interaction activity started. start is a UTC date and time in ISO 8601 format.
• status. The processing status of the interaction. This will be set to one of the following values:
  • Ongoing. The processing of the interaction is still ongoing.
  • Completed. The processing of the interaction completed without errors.
  • InternalError. An error occurred with the processing of the interaction before it could complete.
• duration. A length of time, in milliseconds, that indicates exactly how long the agent remained in this interaction activity. If the agent is currently in this interaction activity, duration is null.
• reason. reason will be one of the following values (or null if any of the conditions are not met):
  • For Ringing interaction activities:
    • Monitor. The user is monitoring the interaction.
  • For Connected interaction activities:
    • Resumed. The agent was reconnected to the interaction when it was resumed from being interrupted.
    • Unparked. The agent was reconnected to the interaction after it was unparked.
    • Monitor. The user is monitoring the interaction.
  • For Wrap interaction activities:
    • Monitor. The user is monitoring the interaction.
  • For Unexpected interaction activities:
    • NumberBusy. The agent being called declined the call or is busy. For a phone call NumberBusy indicates that the agent is already connected to another call, or rejected the call.
    • NoAnswer. A Ringing interaction activity was never answered, or was rejected, and eventually timed out.
    • NumberUnobtainable. The target number could not be reached.
    • CallRejected. The connection was rejected at some point while trying to connect.
    • CallFailed. Exact cause is undetermined.

    • ConnectionUnavailable. While trying to connect the call to the agent, the agent's connection to required media — such as WebRTC — was not available.
      

  • For Failed interaction activities:
    • NumberUnobtainable. The target number could not be reached.
    • CallRejected. The connection was rejected at some point while trying to connect.
    • CallFailed. Exact cause is undetermined.
• interaction. The interaction parameter contains information about the interaction itself.
  • guid. The unique identifier for the interaction. All activities on this interaction have the same Guid.
  • medium. The medium over which the interaction took place.
  • mediumManager. The origin application of the interaction, e.g. “VCC” (Vonage Contact Centre) or “VBC” (Vonage Business Cloud).
  • direction. The direction of the interaction. direction is one of the following values:
    • Inbound (a customer called into the call center)
    • Outbound (the agent called a customer)
    • Internal (an agent called another agent)
• channel. The channel parameter contains information about the agent’s connection to the interaction.
  • guid. Currently this is unused and will return ‘null’. In the future this will contain the unique identifier for the agent’s channel.

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

• name

• eligibleForRouting

• workload

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
}

• agentId. The agent’s ID, as defined in VCC during agent creation.

• type. The type of activity. type will always be Presence for a presence activity.

• category. The category of presence activity. category can be one of the following:

  • Ready. The agent is working and capable of receiving new interactions. You can determine an agent’s actual availability from their presence category in conjunction with their workload activities at the same time. For example, a presence activity of Ready category and a workload activity containing “calls”: 0 indicates that an agent is idle and therefore available.

  • Away. The agent is temporarily away and is not available to receive new interactions. This is commonly used for activities such as breaks.

  • ExtendedAway. The agent is away for an extended period of time and is not available to receive new interactions. This is commonly used for activities such as meetings or lunch.

  • LoggedOut. The agent is logged out of ContactPad, and cannot work on interactions or receive new interactions.

• name. Presences can have a more descriptive name, these are configurable in Contact World. For example, a presence of category ExtendedAway may have a description of Lunch or Meeting.

• eligibleForRouting. A boolean value which indicates whether new interactions can be routed to an agent whilst they are in this presence.

• start. A time stamp which indicates when the presence activity started. start is a UTC date in ISO 8601 format.

• 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.

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:

• reason

• interaction

• channel

• workload

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:

• Live interaction (calls). An interaction that requires an agent’s full attention. Live interactions include phone or video calls.
• Semi-live interaction (semiLive). An interaction that is live with a customer but does not require an agent’s full attention. Semi-live interactions include web chats, for example, Live Agent chats.
• Non-live interaction (nonLive). An interaction that is not live and does not require an agent’s full attention. Non-live interactions include emails, and Salesforce cases and leads.

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, or changes presence.

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 } }

• agentId. The agent’s ID, as defined in VCC during agent creation.

• type. The type of activity. type will always be Workload for a workload activity.

• start. A timestamp which indicates when the workload activity started. start is a UTC date in ISO 8601 format.

• duration
  A length of time, in milliseconds, that indicates exactly how long the agent remained in this workload activity. If the activity represents the agent's current workload, duration is null.

• workload. workload contains a list of all of the agent’s interactions broken down by type.

  • calls. The number of live interactions that the agent is currently handling.
  • semiLive. The number of semi-live interactions that the agent is currently handling.
  • nonLive. The number of non-live interactions that the agent is currently handling.

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

• category
• name
• eligibleForRouting
• reason
• interaction
• channel