Get interactions

1 Overview
2 Placeholder values
- 2.1 Region subdomain
- 2.2 Bearer access token
3 Headers
4 Parameters
- 4.1 start
- 4.2 end
- 4.3 include
5 Pagination
6 Requests
- 6.1 Request interactions including processed
- 6.2 Request page 2 of interactions
7 Responses
- 7.1 Successful response
- 7.2 Example response
- 7.3 Response parameters
  - 7.3.1 InteractionPlanMapping parameters
  - 7.3.2 Channels parameters
  - 7.3.3 Party parameters
  - 7.3.4 Events parameters
  - 7.3.5 Event type values
  - 7.3.6 Event properties
  - 7.3.7 Outcome values
- 7.4 Errors

Overview

The GET /interactions endpoint returns detailed information about a collection of interactions. You can use the response to calculate metrics for a group of interactions within a specified time period.

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:

Name	Type	Required	Description	Example

Name

Type

Required

Description

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

2019-12-20T15:42:39.825Z

`end`

Date

False

The end date and time of the search window. Use ISO 8601 format. 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 an HTTP/1.1 400 status code with the following message:

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

2019-12-20T15:47:39.825Z

`include`

String

False

Determines whether to include interactions that started, interactions that started or ended, or interactions 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 interactions that started.
StartedOrEnded. Searches for interactions that started or ended.
Processed. Searches for interactions that started, ended, or were processed. The inclusion of processed time may mean that interactions completed before the specified time period will be returned.

If you plan to poll this endpoint, 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

Pagination

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

Requests

Request interactions including processed

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

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

The response to the GET /interactions endpoint contains a collection of interaction items. The interaction items are ordered by ascending start time.

Successful response

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

Example response

{
   "meta":{
      "page":1,
      "count":3,
      "pageCount":1,
      "totalCount":2
   },
   "items":[
      {
         "status": "Completed",
         "medium": "Phone",
         "mediumManager": "VCC",
         "guid": "016f7e44-7525-4e37-b0db-5dd09afe592e",
         "conversationGuid": "0c7df94e-a2f9-44e6-80bf-73ffe08f7c34",
         "start": "2020-01-07T12:48:48.023Z",
         "duration":64547,
         "handleTime":47511,
         "talkTime":44005,
         "direction": "Inbound",
         "serviceName": "Report Gp 2",
         "connectTo": "0123456789",
         "connectFrom": "0987654321",
         "categorizedAt": null,
         "outcome": "Handled by agent",
         "interactionPlanMapping":{
            "addressName": "Main Support Number",
            "mappingName": "Mapping1",
            "interactionPlanName": "Customer Support Plan",
            "reportingGroup": "Report Gp 2"
         },
         "channels":[
            {
               "guid": "016f7e44-7525-4e37-b0db-5dd09afe592e",
               "offset":0,
               "duration":62903,
               "handleTime": null, 
               "endReason": "Released",
               "integrationType": null,
               "party":{
                  "id": null,
                  "role": "External",
                  "touchpoint": "0987654321"
               },
               "events":[
                  {
                     "type": "Ringing",
                     "offset":0,
                     "name": null,
                     "duration":0,
                     "properties": null
                  },
                  {
                     "type": "Connected",
                     "offset":0,
                     "name": null,
                     "duration":62903,
                     "properties": null
                  },
                  {
                     "type": "InteractionPlan",
                     "offset":620,
                     "name": "Customer Support Plan",
                     "duration":62283,
                     "properties":{
                        "reportingGroup": "Report Gp 2"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":718,
                     "name": "Welcome",
                     "duration":0,
                     "properties":{
                        "appletType": "Announcement"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":812,
                     "name": "Call Record",
                     "duration":0,
                     "properties":{
                        "appletType": "CallRecording"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":3538,
                     "name": "MainMenu1",
                     "duration":0,
                     "properties":{
                        "appletType": "Menu"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":8078,
                     "name": "SkillTag1",
                     "duration":0,
                     "properties":{
                        "appletType": "SkillTagger"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":8550,
                     "name": "ACD1",
                     "duration":0,
                     "properties":{
                        "appletType": "ACD"
                     }
                  },
                  {
                     "type": "Queue",
                     "offset":8654,
                     "name": "ACD1",
                     "duration":8382,
                     "properties":{
                        "interactionPlan": "0123456789",
                        "interactionPlanName": "Customer Support Plan",
                        "presentedSkills":[
                           "Billing"
                        ],
                        "virtualQueues":[
                           "Billing Queue"
                        ],
                        "targets":[
                           {
                              "virtualQueue": "Billing Queue",
                              "targetTimeToAnswer":30000
                           }
                        ],
                        "result": "Delivered"
                     }
                  },
                  {
                     "type": "CallRecording",
                     "offset":17055,
                     "name": null,
                     "duration":45848,
                     "properties": null
                  }
               ]
            },
            {
               "guid": "41720567-7acd-40a4-94ac-e5a2b60c484c",
               "offset":9682,
               "duration":54865,
		       "handleTime": 47511,
               "endReason": "Released",
               "integrationType": null,
               "party":{
                  "id": "01",
                  "role": "Agent",
                  "touchpoint": "01122334455"
               },
               "events":[
                  {
                     "type": "Ringing",
                     "offset":9682,
                     "name": null,
                     "duration":7354,
                     "properties": null
                  },
                  {
                     "type": "Connected",
                     "offset":17036,
                     "name": null,
                     "duration":44005,
                     "properties": null
                  },
                  {
                     "type": "CallRecording",
                     "offset":17055,
                     "name": null,
                     "duration":43986,
                     "properties": null
                  },
                  {
                     "type": "Wrap",
                     "offset":61041,
                     "name": null,
                     "duration":3506,
                     "properties": null
                  },
                  {
                     "type": "Disposition",
                     "offset":61042,
                     "name": null,
                     "duration":0,
                     "properties":{
                        "disposition": "CallBack"
                     }
                  },
                  {
                     "type": "CallRating",
                     "offset":61043,
                     "name": null,
                     "duration":0,
                     "properties":{
                        "classification": "3"
                     }
                  }
               ]
            }
         ]
      },
      {
         "status": "Completed",
         "medium": "API Case PM",
         "mediumManager": "VCC",
         "guid": "49e5af96-0cd0-45df-b916-8b2b2c4d0070",
         "conversationGuid": "d9480a6b-7795-4427-8ea5-44f0826743bf",
         "start": "2020-01-07T12:49:37.855Z",
         "duration":24872,
         "direction": "Inbound",
		 "handleTime": 21690,
		 "talkTime": 15174,
         "serviceName": "Case Report Group",
         "connectTo": "APIRouting",
         "connectFrom": "",
         "categorizedAt": "2020-01-07T12:53:37.855Z",
         "outcome": "Handled by agent",
         "interactionPlanMapping":{
            "addressName": "API Cases",
            "mappingName": "API Mapping",
            "interactionPlanName": "Case Plan",
            "reportingGroup": "Case Report Group"
         },
         "channels":[
            {
               "guid": "49e5af96-0cd0-45df-b916-8b2b2c4d0070",
               "offset":0,
               "duration":17740,
               "handleTime": null,
               "endReason": "Released",
               "integrationType": null,
               "party":{
                  "id": null,
                  "role": "External",
                  "touchpoint": ""
               },
               "events":[
                  {
                     "type": "Ringing",
                     "offset":0,
                     "name": null,
                     "duration":0,
                     "properties": null
                  },
                  {
                     "type": "Connected",
                     "offset":0,
                     "name": null,
                     "duration":17740,
                     "properties": null
                  },
                  {
                     "type": "InteractionPlan",
                     "offset":96,
                     "name": "Case Plan",
                     "duration":17644,
                     "properties":{
                        "reportingGroup": "Case Report Group"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":623,
                     "name": "Cases",
                     "duration":0,
                     "properties":{
                        "appletType": "ACD"
                     }
                  },
                  {
                     "type": "Queue",
                     "offset":774,
                     "name": "Cases",
                     "duration":2408,
                     "properties":{
                        "interactionPlan": "DanAccount-1",
                        "interactionPlanName": "Case Plan",
                        "result": "Delivered"
                     }
                  }
               ]
            },
            {
               "guid": "8ed8ee4a-f564-45c7-b0fc-2ee3c094bb2b",
               "offset":3107,
               "duration":21765,
               "handleTime": 21690,
               "endReason": "Released",
               "integrationType": null,
               "party":{
                  "id": "002",
                  "role": "Agent",
                  "touchpoint": "01122334455"
               },
               "events":[
                  {
                     "type": "Ringing",
                     "offset":3107,
                     "name": null,
                     "duration":75,
                     "properties": null
                  },
                  {
                     "type": "Connected",
                     "offset":3182,
                     "name": null,
                     "duration":15174,
                     "properties": null
                  },
                  {
                     "type": "Wrap",
                     "offset":18356,
                     "name": null,
                     "duration":6516,
                     "properties": null
                  },
                  {
                     "type": "Disposition",
                     "offset":18357,
                     "name": null,
                     "duration":0,
                     "properties":{
                        "disposition": "CallBack"
                     }
                  },
                  {
                     "type": "CallRating",
                     "offset":18358,
                     "name": null,
                     "duration":0,
                     "properties":{
                        "classification": "3"
                     }
                  }
               ]
            }
         ]
      },
      {
         "guid": "03d154eb-f3fa-4151-bf61-eff2e8197343",
         "conversationGuid": "5c778f8f-bf19-467c-b22e-255fee5b06e1",
         "medium": "Webchat",
         "mediumManager": "VCC",
         "start": "2020-01-07T12:49:37.955Z",
         "duration":41005,
         "handleTime": null,
         "talkTime": null,
         "direction": "Inbound",
         "serviceName": null,
         "connectTo": "c038a638-f9fb-4cb6-948d-7a4ce6667798",
         "categorizedAt": null,
         "outcome": "Abandoned in bot",
         "interactionPlanMapping":{
            "addressName": "Main route",
            "mappingName": "Digital",
            "interactionPlanName": "Digital Plan",
            "reportingGroup": null
         },
         "channels":[
            {
               "guid": "03d154eb-f3fa-4151-bf61-eff2e8197343",
               "offset":0,
               "duration":41005,
               "endReason": "Released",
               "integrationType": null,
               "party":{
                  "id": null,
                  "role": "External",
                  "touchpoint": null,
                  "touchpointKey": "6257c572-a081-4788-a5b3-6c6abdbb25cd"
               },
               "events":[
                  {
                     "type": "Ringing",
                     "offset":0,
                     "name": null,
                     "duration":0,
                     "properties": null
                  },
                  {
                     "type": "Connected",
                     "offset":0,
                     "name": null,
                     "duration":41005,
                     "properties": null
                  },
                  {
                     "type": "InteractionPlan",
                     "offset":142,
                     "name": "Digital Plan",
                     "duration":40863,
                     "properties":{
                        "reportingGroup": null
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":1310,
                     "name": "virtual assistant",
                     "duration":0,
                     "properties":{
                        "appletType": "VirtualAssistant"
                     }
                  },
                  {
                     "type": "VirtualAssistant",
                     "offset":2249,
                     "name": "Simple Agent",
                     "duration":38217,
                     "properties":{
                        "result": "Resolved",
                        "messageCount": "10"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":40687,
                     "name": "DR route to queue",
                     "duration":0,
                     "properties":{
                        "appletType": "DataRouter"
                     }
                  },
                  {
                     "type": "Applet",
                     "offset":40919,
                     "name": "Resolved announcement",
                     "duration":0,
                     "properties":{
                        "appletType": "Announcement"
                     }
                  }
               ]
            }
         ]
      }
   ],
   "upTo": "2020-01-07T12:51:27.982Z",
   "latestUpdate": "2020-01-07T12:51:24.919Z"
}

Response parameters

Each interaction item in the collection contains the following parameters:

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`status`	String	The current state of the interaction. Possible values: `Ongoing`, `Completed`, `InternalError`.	`"Completed"`
`medium`	String	The type of communication method.	`"Phone"`
`mediumManager`	String	The origin application of the interaction, for example, `VCC` (Vonage Contact Centre) or `VBC` (Vonage Business Cloud).	`"VCC"`
`guid`	String (GUID)	The unique identifier for an interaction.	`"016f7e44-7525-4e37-b0db-5dd09afe592e"`
`conversationGuid`	String (GUID)	The unique identifier for the conversation. Individual interactions can be part of a larger conversation. For example, if a customer requests a callback from an agent, both interactions share the same conversation GUID.	`"0c7df94e-a2f9-44e6-80bf-73ffe08f7c34"`
`start`	String (ISO 8601)	The time when the interaction started.	`"2020-01-07T12:48:48.023Z"`
`duration`	Integer (ms)	The length of time the interaction lasted, in milliseconds. `null` if the interaction is still ongoing.	`64547`
`handleTime`	Integer (ms)	The interaction's handle time. A combination of all channels' handle times; may exceed the length of the interaction.	`47511`
`talkTime`	Integer (ms)	The amount of time a channel participant spent in the connected channel state while another channel participant was also connected, where at least one participant is an agent. Calculated only for channels with the role of `Agent` or `External`, minus CCR-initiated external channels.	`44005`
`direction`	String	The direction of the interaction. Possible values: `Inbound`, `Outbound`, `Internal`.	`"Inbound"`
`serviceName`	String	The service name assigned to the interaction. If using Interaction Plans Manager: the name of the destination, interaction plan, or reporting group. Otherwise: the service name assigned to the interaction plan.	`"Report Gp 2"`
`connectTo`	String	The address of the party being contacted. For a phone call, the phone number being called.	`"0123456789"`
`connectFrom`	String	The address of the party that initiated the interaction. For a phone call, their phone number.	`"0987654321"`
`categorizedAt`	String (ISO 8601)	The time at which the interaction was categorized. `null` if not categorized. Conversation Analyzer, if enabled, categorizes an interaction by matching phrases in the transcript against a categorization profile.	`null`
`outcome`	String	A high-level description of the outcome. `null` if the interaction is still ongoing. See the Outcome values later in the page.	`"Handled by agent"`
`interactionPlanMapping`	Object	Details about the mapping used to link the address to the destination interaction plan. `null` for outbound interactions unless the agent consults or transfers to an interaction plan. See InteractionPlanMapping parameters section later in the page.	`{...}`
`channels`	Array	A collection of all channels within the interaction. See the Channels parameters section later in the page.	`[...]`
`latestUpdate`	String (ISO 8601)	The time of the most recent interaction event available in the Insights Stats API. The difference between the current time and `latestUpdate` represents the delay between an interaction event and the corresponding statistic becoming available.	`"2020-01-07T12:51:24.919Z"`

InteractionPlanMapping parameters

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`addressName`	String	The name of the address contacted by the external party.	`"Main Support Number"`
`mappingName`	String	The name of the mapping used to connect the address to the interaction plan.	`"Mapping1"`
`interactionPlanName`	String	The name of the destination interaction plan.	`"Customer Support Plan"`
`reportingGroup`	String	A label used to differentiate interaction plans. Useful for reporting on similar types of interaction plans and their associated interactions.	`"Report Gp 2"`

Channels parameters

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`guid`	String (GUID)	The unique identifier for the channel.	`"41720567-7acd-40a4-94ac-e5a2b60c484c"`
`offset`	Integer (ms)	The length of time after the start of the interaction that the channel started.	`9682`
`duration`	Integer (ms)	The length of time the channel was involved with the interaction. `null` if the channel is still ongoing.	`54865`
`handleTime`	Integer (ms)	The amount of time a controlling or non-controlling agent spent actively working on the interaction. Calculated by adding the duration of the connected and wrap channel states for that participant, and subtracting the duration of any interrupted or parked channel states.	`47511`
`endReason`	String	The reason the channel ended. Possible values: `Released`, `Busy`, `NoAnswer`, `Unreachable`, `Rejected`, `Failed`, `ConnectionUnavailable`.	`"Released"`
`integrationType`	String	The type of channel integration. `null` indicates a VCC channel (not an integration). `VBC` indicates VBC channel integration.	`null`
`party`	Object	Information about the party on the channel. See the Party parameters section later in the page	`{...}`
`events`	Array	A collection of events that happened on the channel. Use `events` to construct a timeline of each party's experience of the interaction. Events can overlap. See the Events parameters section later in the page.	`[...]`

Party parameters

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`id`	String	An identifying name for the party. If `role` is `Agent`, contains the agent's ID as defined in the VCC Admin Portal. For a channel created by a Call Connect Router, the value is `CCRConnect`.	`"01"`
`role`	String	The role of the party. Possible values: `External`, `Agent`, `Monitor`, `Voicemail`.	`"Agent"`
`touchpoint`	String	The address of the party, such as a phone number (if known).	`"01122334455"`

Events parameters

Parameter	Type	Description	Example

Parameter	Type	Description	Example
`type`	String	The type of event. See the Event type Values section later in the page.	`"Connected"`
`offset`	Integer (ms)	The length of time after the start of the interaction that the channel event started.	`17036`
`name`	String	The name associated with the event. For `Applet` and `AppletFailed` events: the name of the applet. For `InteractionPlan`: the interaction plan name. For `Queue`: the queue name. For `QuickMessageLeft`: the quick message name. For `VirtualAssistant`: the Virtual Assistant name. For `VoicemailRecording`: the voicemail message ID. `null` in all other cases.	`"ACD1"`
`duration`	Integer (ms)	The length of time the channel event was ongoing. `null` if the event is still ongoing.	`44005`
`properties`	Object	A collection of properties dependent on the event type. See Event properties below.	`{"result":"Delivered"}`

Event type values

Value	Description

Value	Description
`Abandoned`	The agent selected Abandon in ContactPad.
`AgentQueue`	The time in which an agent was queuing.
`Applet`	An applet was run on this channel.
`AppletFailed`	An applet failed on this channel.
`AudioProblemReported`	An agent reported an issue with the quality of the call's audio.
`CallRating`	The agent rated the call. The `classification` property contains the rating value (null or 1–5).
`CallRecording`	Channel was being recorded.
`Connected`	Channel was connected and capable of communicating with other connected parties.
`Consult`	The participant on the channel attempted to connect to another participant to consult with them.
`DataSourceValueAcquired`