Get agent interaction activities

The GET /agent-activities/interactions endpoint gets information about agents’ interaction activities. Using this endpoint you can determine exactly how long an agent was working on an interaction, and how much time they spent on each part of that interaction.

Each agent interaction activity indicates that an agent spent time working on an interaction. Each interaction activity is returned as a period of time, defined by a start date and a duration (if the activity has completed).

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.

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

state

Specify an interaction state to limit the response to include only interaction activities relating to the specified state.

Possible values are:

• Ringing.
• Failed.
• Unexpected.
• Connected.
• Wrap.

By default, interaction activities relating to all states are included in the response.

direction

Specify the direction of the interaction to limit the response to include only interaction activities in the specified direction.

Possible values are:

• Inbound.
• Outbound.
• Internal.

By default all directions of interaction activities are included in the response.

Pagination

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

Requests

Request agent activities interactions including processed

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

curl -L -X GET "https://***.api.newvoicemedia.com/stats/agent-activities/interactions?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/interaction requests contain interaction activities for the specified time period.

Successful responses

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

Example response

{
  "meta": {
    "page": 1,
    "count": 16,
    "pageCount": 1,
    "totalCount": 16
  },
  "items": [
    {
      "agentId": "1234",
      "start": "2019-12-19T10:26:26.284Z",
      "status": "Completed",
      "duration": 6309,
      "state": "Wrap",
      "reason": null,
      "interaction": {
        "guid": "cba1ab4f-dcac-442e-be2f-0314d085f966",
        "medium": "API Case PM",
        "mediumManager": "VCC",
        "direction": "Inbound"
      },
      "channel": {
        "guid": null
      }
    }
		...
  ],
  "upTo": "2019-12-19T11:08:40.128Z"
}

Interaction 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 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.
• state. The type of activity the agent was engaged in on the interaction. The different interaction states tracked are:
  • 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 Connect 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.
• 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. A value that indicates how the agent was involved in the interaction. Direction can be one of inbound, outbound, or internal. If the agent participated in the interaction multiple times, the activities relating to each participation may have different directions.
    • Inbound. The agent received the interaction from a queue or a cold transfer. Note that this does not include receiving a callback (see outbound) or receiving a consult (see Internal).
    • Outbound. The agent initiated an outbound interaction to an external participant or received a callback.
    • Internal. The agent received a consult from another agent or initiated an internal interaction to another agent.
• channel. The Channel parameter contains information about the agent’s connection to the interaction.
  • guid. The unique identifier for the agent’s channel.

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