Get interactions
- Helen Griffith
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.
Headers
Header parameters in Requests (Insights Stats API) apply to this endpoint.
Authorization scopes supported:
| Scope | Access granted |
|---|---|
stats | Entire endpoint |
Parameters
The endpoint accepts the following query string parameters:
start
| Type | Required | Example |
|---|---|---|
| Date | True | 2019-12-20T15: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 the FAQ (Insights Stats API).
end
| Type | Required | Example |
|---|---|---|
| Date | False | 2019-12-20T15:47:39.825Z |
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 a HTTP/1.1 400 status code with the following message:
{
"message":"Request window size limit exceeded 31 days"
}
include
| Type | Required | Example |
|---|---|---|
| String | False | Started |
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 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.
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",
"connectToKey":null,
"connectFrom":null,
"connectFromKey":"6257c572-a081-4788-a5b3-6c6abdbb25cd",
"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"
}
items
Each interaction item in the collection contains the following parameters:Â The Virtual Assistant did not resolve the interaction. The party working with the Virtual Assistant abandoned the interaction during the session. The Virtual Assistant did not resolve the interaction. The party working with the Virtual Assistant reached the end of the flow without resolution, and the Virtual Assistant escalated the interaction to another applet or to a live agent. {"appletType": "MessageTake"} {"targetAgentId": "1234"} After the list of interactions, the response returns a The difference between the current time and the medium. The type of communication method.mediumManager. The origin application of the interaction, for example, 'VCC' (Vonage Contact Centre) or 'VBC' (Vonage Business Cloud).start. The time when the interaction started. start is a UTC date in ISO 8601 format.guid. The unique identifier for an interaction.conversationGuid. Individual interactions can be part of a larger conversation, and this value is the unique identifier for the conversation. For example, if a customer requests a callback from an agent both interactions will have the same conversation GUID.status. The current state of the interaction. Possible values are:duration. A length of time, in milliseconds, that indicates exactly how long the interaction lasted. If the interaction is still ongoing, the duration is null.handleTime. An interaction's handle time is a combination of all channels' handle times therefore can exceed the length of the interaction.talkTime. The amount of time a channel participant spent in the connected channel state, while another channel participant was also connected — at least one of these participants must be an agent. The time excludes any connected substates for either participant. Talk time is calculated only for channels with the role of either agent or external — minus external channels that were CCR initiated.direction. The direction of the interaction. direction is one of the following values:serviceName.connectTo. The address of the party that was being contacted within the interaction. For a phone call connectTo is the phone number being called.connectFrom. The address of the party that initiated the interaction. For a phone call connectFrom is their phone number.categorizedAt. The time at which the interaction was categorized. categorizedAt is a UTC date in ISO 8601 format. If an interaction hasn’t been categorized, the value is null. Conversation Analyzer—if enabled—categorizes an interaction by matching phrases in the interaction’s transcript against a categorization profile.outcome. A high-level description of the outcome for the interaction. If the interaction is still ongoing, the outcome is null. An interaction may have more than one possible value — the one with the highest level of importance is returned. Possible values, in order of importance, are:interactionPlanMapping. Interaction plan mappings define where interactions should go. For inbound interactions, the interactionPlanMapping section contains details about the mapping used to link the address that the external party contacted to the destination interaction plan. For outbound interactions, interactionPlanMapping will be null unless the agent consults or transfers to an interaction plan.addressName. The name of the address contacted by the external party.mappingName. The name of the mapping used to connect the address to the interaction plan.interactionPlanName. The name of the destination interaction plan.reportingGroup. A label used to differentiate interaction plans. Useful for reporting on similar types of interaction plans and their associated interactions.channels. A collection of all channels within the interaction. Each channel represents a party on the interaction, such as an Agent or a Customer.guid. The unique identifier for the channel.offset. A length of time, in milliseconds, that indicates the length of time after the start of the interaction that the channel started.duration. A length of time, in milliseconds, that indicates exactly how long the channel was involved with the interaction. If the channel is still ongoing, the duration is null.handleTime. The amount of time a controlling or non-controlling agent or a bot participant spent actively working on the interaction. The time is 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. party. party contains information about the party on the channel:id. An identifying name for the party. If role is “Agent”, id contains the agent’s ID, as defined in the Vonage Contact Center (VCC) Admin Portal during agent creation. For a channel created by a Call Connect Router, the value is “CCRConnect”.role. The role of the party. Possible values are:touchpoint. The address of the party, such as a phone number (if known).endReason. The reason the channel ended. Possible values are:integrationType. The type of channel integration. Possible values are:events. A collection of events that happened on the channel. Use events to construct a timeline of each party’s experience of the interaction. Note that events can overlap.type. The type of event. Possible values are:classification property contains the call rating value provided by the agent. The value can be null (not set) or a number from 1 to 5.Disposition is used to group interactions by outcome.result property value will be either Resolved, Escalated or Abandoned. The messageCount property indicates the total number of sent and received messages.offset. A length of time, in milliseconds, that indicates the length of time after the start of the interaction that the channel event started.name.name holds the name of the queue.name holds the name of the Interaction Plan.name holds the unique voicemail message ID.name is null.duration. A length of time, measured in milliseconds, which indicates exactly how long the channel event was ongoing. If the channel event is still ongoing, the duration is null.properties. A collection of properties, dependent on the type of channel event. The following table contains the available properties:Channel event type Possible properties Description AgentQueue {“result”:“AgentRecall”} The queuing agent canceled the queue event and recalled the customer. AgentQueue {“result”:“AgentTransfer”} The queuing agent transferred the party on hold into the queue and left the interaction. AgentQueue, Queue {“interactionPlan”:“01234567890”} The ID of the interaction plan. The ID is the inbound address of the interaction plan for older plans and the guid of the interaction plan for newer plans. ( interactionPlan will be deprecated in v4 of the API.)AgentQueue, Queue {“interactionPlanName”:“Customer Support Plan”} The name of the interaction plan at the time that the interaction entered the queue. AgentQueue, Queue {“presentedSkills”:[“Skill1”,“Skill2”]} An array of skills that the interaction was tagged with when it entered the queue. AgentQueue, Queue {“result”:“AgentDeclineBreakout”} The agent declined the interaction. AgentQueue, Queue {“result”:“Delivered”} The interaction was successfully connected to an agent. AgentQueue, Queue {“result”:“HangUp”} The customer ended the interaction whilst queuing. AgentQueue, Queue {“result”:“MaxEstimatedWaitTime”} The estimated time the interaction would wait was higher than the maximum allowed, and it was routed out of the queue. AgentQueue, Queue {“result”:“NoAgentsBreakout”} There are no agents available to serve the queue, and the interaction was routed out of the queue. AgentQueue, Queue {“result”:“QueueCapacityBreakout”} The queue was at the configured capacity and the interaction was routed out of the queue. AgentQueue, Queue {“result”:“QueueTimeBreakout”} The interaction had queued for the maximum amount of allowed time and it was routed out of the queue. AgentQueue, Queue {“result”:“VoluntaryBreakout”} The customer has chosen to leave the queue when offered. AgentQueue, Queue {“targets”:[{“virtualQueue”:“VirtualQueue1”, “targetTimeToAnswer”:20000}]} An array of virtual queue SLA targets, with the target time to answer in milliseconds. AgentQueue, Queue {“virtualQueues”:[“VirtualQueue1”,“VirtualQueue2”]} An array of virtual queues that the interaction entered. Applet {“appletType”:“VoiceMail”} Indicates the type of applet that was run. AudioProblemReported {“classification”:“echo”} Indicates that the agent reported a problem with their call audio. The classification provides information about the type of audio problem. CallRating {“classification”:“3”} The call rating classification provided by the agent. DataSourceValueAcquired {“value”:“CASE-123456789”} The value that was associated with the channel. DeliveryFailed {“type”:“ConnectionUnavailable”} Indicates the type of media connection failure. The possible values match those of endReason.Disposition {“disposition”:“CallBack”} The disposition code provided by the agent. Held {“initiatingAgentId”:“1234”} The ID of the agent that placed the channel on hold. Held {“type”:“Held”} The Held type of Held event represents a period when the channel was on hold. Held {“type”:“Interrupted”} The Interrupted type of Held event represents a period when the channel was interrupted. Held {“type”:“Parked”} The Parked type of Held event represents a period when the channel was parked. InteractionPlan {“reportingGroup”:“Report Group Omega”} A label used to report on data from multiple interaction plans. Monitoring {“type”:“ListenIn”} Indicates that a monitoring party ( role is Monitor) is currently monitoring the interaction. The monitor can listen to the interaction but other parties will be unaware of the monitor.Monitoring {“type”:“Watch”} Indicates that a monitoring party ( role is Monitor) is currently monitoring the interaction. The monitor can view the live transcript of the interaction but other parties will be unaware of the monitor.Monitoring {“type”:“Coach”} Indicates that a monitoring party ( role is Monitor) is currently monitoring the interaction. The monitor can communicate with the agent party, but the external party will be unaware of the monitor.Monitoring {“type”:“Join”} Indicates that a monitoring party ( role is Monitor) is currently monitoring the interaction. The monitor can communicate with both the agent and external party.VirtualAssistant {"messageCount":"Abandoned"} The total number of sent and received messages. VirtualAssistant {"result":"Abandoned"} VirtualAssistant {"result":"Escalated"} VirtualAssistant {"result":"Resolved"} The Virtual Assistant resolved the interaction. The party working with the Virtual Assistant reached the end of the flow, and the Virtual Assistant deemed the interaction complete. VoicemailRecording Indicates the type of applet that created the voicemail recording. This could be "VoiceMail" or "MessageTake". VoicemailRecording The ID of the agent that the voicemail was left for. This is set if the appletType was "VoiceMail".latestUpdatelatestUpdate parameter. The value of latestUpdate is the time of the most recent interaction event that is available using the Insights Stats API.latestUpdate represents the delay between an interaction event, and the corresponding statistic being available.
We aim to minimise the delay so that the Insights Stats API data is as up-to-date as possible, but the delay may increase during busy periods or service disruption. If you require near real-time statistics, the latestUpdate value may be useful so you can respond appropriately to any delay.
For information, see Trying out Vonage Contact Center APIs.
