Get agent interaction activities

1 Overview
2 Placeholder values
- 2.1 Region subdomain
- 2.2 Bearer access token
3 Headers
4 Parameters
5 Pagination
6 Requests
- 6.1 Request agent activities interactions including processed
- 6.2 Request page 2 of agent activities interactions
7 Responses
- 7.1 Successful responses
- 7.2 Example response
- 7.3 Response parameters
- 7.4 Errors

Overview

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.

Placeholder values

The example code in this documentation uses the following placeholder values. Replace each placeholder before sending requests.

Region subdomain

Replace *** in the base URL with the subdomain for your region:

Region	URL subdomain	Base URL

Region	URL subdomain	Base URL
EMEA	`emea`	`https://emea.api.cc.vonage.com/`
USA	`nam`	`https://nam.api.cc.vonage.com/`
APAC	`apac`	`https://apac.api.cc.vonage.com/`

Bearer access token

Replace <ACCESS_TOKEN> with your bearer access token. You must include a valid bearer access token in every request. For information about obtaining a bearer access token, see How to authenticate with a Vonage Contact Center (VCC) API.

Headers

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

Authorization scopes supported:

Scope	Access granted

Scope	Access granted
`stats`	Entire endpoint

Parameters

The endpoint accepts the following query string parameters:

Nme	Type	Required	Descriptions	Example

Nme	Type	Required	Descriptions	Example
`start`	Date	True	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 the FAQ page.	`2019-12-10T15:42:39.825Z`
`end`	Date	False	The end date and time of the search window. Use ISO 8601 format. Default is now.	`2019-12-10T15:47:39.825Z`
`include`	String	False	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 that using the StartedOrEnded or Processed values can result in duplicate items being returned across search windows. The default value is Started.	`Started`
`agentId`	String	False	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.	`1234`
`state`	String	False	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.	`Connected`
`direction`	String	False	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.	`Inbound`

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

Response parameters

Interaction activities contain the following parameters:

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`agentId`	String	The agent's ID, as defined in VCC during agent creation.	`"1234"`
`start`	String (ISO 8601)	A timestamp that indicates when the interaction activity started. UTC date and time in ISO 8601 format.	`"2019-12-19T10:26:26.284Z"`
`status`	String	The processing status of the interaction. Possible values: `Ongoing`: the processing is still ongoing. `Completed`: the processing completed without errors. `InternalError`: an error occurred with the processing before it could complete.	`"Completed"`
`duration`	Integer (ms)	The length of time, in milliseconds, that indicates exactly how long the agent remained in this interaction activity. `null` if the agent is currently in this interaction activity.	`6309`
`state`	String	The type of activity the agent was engaged in on the interaction. Possible values: `Ringing`: the agent was offered the interaction (for a phone call, the period in which the phone was ringing). `Connected`: the agent was connected to the interaction (for a phone call, the period in which parties are connected and able to talk; if an agent parks a phone call, the Connected activity ends and 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 and a new Connected activity starts when the interaction is resumed). `Wrap`: the agent was in the wrap period at the end of an interaction, normally used for post-interaction work such as note taking. `Unexpected`: usually occurs after Ringing; indicates that an agent who was available for work did not answer their phone, or their line was busy on another call. `Failed`: can occur at any time during an interaction; possible causes are network congestion, a fault on the line, or a configuration issue.	`"Wrap"`
`reason`	String	The reason for the current activity state. `null` if no condition is met. For `Ringing`: `Monitor`: the user is monitoring the interaction. For `Connected`: `Resumed`: the agent was reconnected when the interaction was resumed from being interrupted. `Unparked`: the agent was reconnected after the interaction was unparked. `Monitor`. For `Wrap`: `Monitor`. For `Unexpected`: `NumberBusy`: the agent declined or is busy (for a phone call, already connected to another call or rejected). `NoAnswer`: never answered, rejected, and eventually timed out. `NumberUnobtainable`: the target number could not be reached. `CallRejected`: the connection was rejected while trying to connect. `CallFailed`: exact cause is undetermined. `ConnectionUnavailable`: the agent's connection to required media such as WebRTC was not available. For `Failed`: `NumberUnobtainable`, `CallRejected`, `CallFailed`.	`null`
`interaction.guid`	String (GUID)	The unique identifier for the interaction. All activities on this interaction have the same GUID.	`"cba1ab4f-dcac-442e-be2f-0314d085f966"`
`interaction.medium`	String	The medium over which the interaction took place.	`"Phone"`
`interaction.mediumManager`	String	The origin application of the interaction, for example, `VCC` (Vonage Contact Centre) or `VBC` (Vonage Business Cloud).	`"VCC"`
`interaction.direction`	String	A value that indicates how the agent was involved in the interaction. If the agent participated multiple times, activities relating to each participation may have different directions. Possible values: `Inbound`: the agent received the interaction from a queue or a cold transfer (does not include receiving a callback or a consult). `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.	`"Inbound"`
`channel.guid`	String (GUID)	The unique identifier for the agent's channel.	`"41720567-7acd-40a4-94ac-e5a2b60c484c"`

Manual wrap activities

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

Errors

Some interactions may be returned with status: InternalError. This can occur when a processing error occurs during the interaction, for example, when a looping call plan generates a large number of routing events. The data for these interactions may be incomplete.

For more information, see FAQ (Insights Stats API).