Get a single interaction (Insights Stats API)

The GET /interactions/{guid} endpoint returns detailed information about a single interaction.

In this page


Most URLs in the example code use the following values:

Headers

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

Authorization scopes supported:

ScopeAccess granted
statsEntire endpoint

Parameters

The endpoint accepts the following path parameter:

guid

TypeRequiredExample
StringTrue016f3105-0854-43e2-9d2a-33ef02aff410

The unique identifier for the interaction.

Requests

Request interaction statistics for 9b0e5ced-514f-4415-82cf-2d16955965d7

curl -L -X GET "https://***.api.newvoicemedia.com/stats/interactions/9b0e5ced-514f-4415-82cf-2d16955965d7" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json"

Responses

The response to the GET /interactions/{guid} endpoint contains a singe interaction object.

A successful request returns a 200 Success code with a JSON object in the response body.

Example response

{
  "status": "Completed",
  "medium": "Phone",
  "mediumManager": "VCC",
  "start": "2020-01-07T16:50:59.899Z",
  "guid": "016f7e44-7556-4747-9982-de543dfbe27f",
  "conversationGuid": "2b60783a-c74c-4938-b843-ce496c54ef81",
  "duration": 83340,
  "direction": "Inbound",
  "serviceName": "Report Gp 2",
  "connectTo": "1234567890",
  "connectFrom": "0987654321",
  "categorizedAt": "2020-01-07T16:56:59.899Z",
  "interactionPlanMapping": {
    "addressName": "Main Support Number",
    "mappingName": "Mapping1",
    "interactionPlanName": "Customer Support Plan",
 	"reportingGroup": "Report Gp 2"
  },
  "channels": [
    {
      "guid": "016f7e44-7556-4747-9982-de543dfbe27f",
      "offset": 0,
      "duration": 81328,
      "endReason": "Released",
      "integrationType": null,
      "party": {
        "id": null,
        "role": "External",
        "touchpoint": "01256700817"
      },
      "events": [
        {
          "type": "Ringing",
          "offset": 0,
          "name": null,
          "duration": 0,
          "properties": null
        },
        {
          "type": "Connected",
          "offset": 0,
          "name": null,
          "duration": 81328,
          "properties": null
        },
        {
          "type": "InteractionPlan",
          "offset": 307,
          "name": "Customer Support Plan",
          "duration": 81021,
          "properties": {
            "reportingGroup": "Report Gp 2"
          }
        },
        {
          "type": "Applet",
          "offset": 362,
          "name": "Welcome",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 437,
          "name": "AnnouncementA",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 488,
          "name": "AnnouncementB",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 553,
          "name": "AnnouncementC",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 606,
          "name": "AnnouncementD",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 670,
          "name": "AnnouncementE",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 721,
          "name": "AnnouncementF",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 785,
          "name": "AnnouncementG",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 849,
          "name": "AnnouncementH",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 910,
          "name": "AnnouncementI",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 982,
          "name": "AnnouncementJ",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1041,
          "name": "AnnouncementK",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1097,
          "name": "AnnouncementL",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1161,
          "name": "AnnouncementM",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1232,
          "name": "AnnouncementN",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1589,
          "name": "AnnouncementO",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1678,
          "name": "AnnouncementP",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1740,
          "name": "AnnouncementQ",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1795,
          "name": "AnnouncementR",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1846,
          "name": "AnnouncementS",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1898,
          "name": "AnnouncementT",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 1962,
          "name": "AnnouncementU",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2018,
          "name": "AnnouncementV",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2088,
          "name": "AnnouncementW",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2143,
          "name": "AnnouncementX",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2209,
          "name": "AnnouncementY",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2260,
          "name": "AnnouncementZ",
          "duration": 0,
          "properties": {
            "appletType": "Announcement"
          }
        },
        {
          "type": "Applet",
          "offset": 2315,
          "name": "Call Record",
          "duration": 0,
          "properties": {
            "appletType": "CallRecording"
          }
        },
        {
          "type": "Applet",
          "offset": 10834,
          "name": "MainMenu1",
          "duration": 0,
          "properties": {
            "appletType": "Menu"
          }
        },
        {
          "type": "Applet",
          "offset": 12681,
          "name": "SkillTag1",
          "duration": 0,
          "properties": {
            "appletType": "SkillTagger"
          }
        },
        {
          "type": "Applet",
          "offset": 13083,
          "name": "ACD1",
          "duration": 0,
          "properties": {
            "appletType": "ACD"
          }
        },
        {
          "type": "Queue",
          "offset": 13164,
          "name": "ACD1",
          "duration": 7140,
          "properties": {
            "interactionPlan": "1234567890",
            "interactionPlanName": "Customer Support Plan",
            "presentedSkills": [
              "Billing"
            ],
            "result": "Delivered"
          }
        },
        {
          "type": "CallRecording",
          "offset": 20322,
          "name": null,
          "duration": 61006,
          "properties": null
        }
      ]
    },
    {
      "guid": "6608465f-46fc-4d51-85f7-804a306fcc2b",
      "offset": 14087,
      "duration": 69253,
      "endReason": "Released",
      "integrationType": null,
      "party": {
        "id": "01",
        "role": "Agent",
        "touchpoint": "01122334455"
      },
      "events": [
        {
          "type": "Ringing",
          "offset": 14087,
          "name": null,
          "duration": 6217,
          "properties": null
        },
        {
          "type": "Connected",
          "offset": 20304,
          "name": null,
          "duration": 59165,
          "properties": null
        },
        {
          "type": "CallRecording",
          "offset": 20322,
          "name": null,
          "duration": 59147,
          "properties": null
        },
        {
          "type": "Wrap",
          "offset": 79469,
          "name": null,
          "duration": 3871,
          "properties": null
        },
        {
          "type": "Disposition",
          "offset": 79470,
          "name": null,
          "duration": 0,
          "properties": {
            "disposition": "CallBack"
          }
        },
        {
          "type": "CallRating",
          "offset": 79471,
          "name": null,
          "duration": 0,
          "properties": {
            "classification": "3"
          }
        }
      ]
    }
  ]
}

A single interaction contains the following parameters: 

  • 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:
    • Ongoing. The interaction is still in progress.
    • Completed. The interaction has ended.
    • InternalError. A processing error occurred during the interaction.
  • 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.
  • 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)
  • serviceName.
    • If you are using Interaction Plans Manager:
      • The service name value assigned to the interaction. Service name can be the name of the destination used to contact VCC, the name of the interaction plan in which the interaction was first processed, or the reporting group of the interaction plan in which the interaction was first processed.
    • Otherwise:
      • The service name value assigned to the interaction plan.
  • 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.
  • 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 on the interaction, the duration is null.
    • 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:
        • External. This most commonly indicates the customer’s channel, but any call to a number not linked to an agent will show as External.
        • Agent. Indicates the VCC agent’s channel.
        • Monitor. Indicates the VCC supervisor monitor’s channel.
        • Voicemail. Indicates that the there is no actual person on the channel, and represents an external party recording a message to voicemail.
      • touchpoint. The address of the party, such as a phone number (if known).
    • endReason. The reason the channel ended. Possible values are:
      • Released. Indicates the channel participant hung up their device or clicked Release.
      • Busy. The channel entered an alerting state, but the channel participant did not accept because their device was busy. The most common example is an inbound phone call where the phone is already engaged. In other parts of the product, this is known by the newer name of DeviceBusy.
      • NoAnswer. The channel entered an alerting state, but the channel participant did not accept the interaction within the timeout for accepting interactions. In other parts of the product, this is known by the newer name of NotAccepted.
      • Unreachable. The channel entered an alerting state, but the channel participant did not accept because their device — such as their phone or microphone — was not reachable. In other parts of the product, this is known by the newer name of DeviceUnreachable.
      • Rejected. The channel entered an alerting state, but the interaction was manually or automatically rejected when assigned to the agent. For example, an agent is offered a chat and they click Reject.
      • Failed. The channel entered an alerting state, but the channel participant did not connect for an unexpected reason, possibly due to configuration or network errors. In other parts of the product, this is known by the newer name of Fault.
      • ConnectionUnavailable. The channel entered an alerting state, but could not be connected to the agent because the required media channel — currently phone interactions using WebRTC only — was not available.
    • integrationType. The type of channel integration. Possible values are:
      • null. Indicates a VCC channel (not an integration)
      • VBC.  Indicates VBC channel integration.
    • 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:
        • Abandoned. The agent clicked Abandon in ContactPad.
        • AgentQueue. The time in which an agent was queuing during a warm transfer to queue.
        • Applet. An applet was run 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 call rating value provided by the agent. The value can be null (not set) or a number from 1 to 5.
        • CallRecording. Channel was being recorded.
        • Connected. Channel was connected and capable of communicating with other connected parties.
        • DataSourceValueAcquired. A customer specified value, such as from a CRM system, was associated with this channel.
        • DeliveryFailed. Indicates the agent's connection to required media — such as WebRTC — failed.
        • Disposition. The disposition code provided by the agent. Disposition codes describe the outcome of an interaction. Disposition is used to group interactions by outcome.
        • Held. Channel was placed on hold, parked, or interrupted, and the channel was unable to communicate with the other channels.
        • InteractionPlan. Channel entered an Interaction Plan. The duration of the event is from when the channel enters the plan until the channel disconnects or enters another interaction plan.
        • Monitoring. Indicates that a monitoring party (role is Monitor) is currently monitoring the channel.
        • Ringing. The period in which the channel was being offered to the party.
        • Queue. Channel was in a queue waiting to be answered.
        • VirtualAssistant. Channel engaged with a Virtual Assistant. The result property value will be either ResolvedEscalated or Abandoned
        • VoicemailRecording. Channel left a voicemail. The duration of the event represents the length of the recorded message.
        • Wrap. The time spent doing post interaction work. Wrap only appears on agent channels.
      • 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.
        • If the channel event is of type Queue, name holds the name of the queue.
        • If the channel event is of type InteractionPlan, name holds the name of the Interaction Plan.
        • If the channel event is of type VoicemailRecording, name holds the unique voicemail message ID.
        • In all other cases, 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 typePossible propertiesDescription
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 channel. The monitor can listen to the channel but other parties will be unaware of the monitor.
Monitoring{“type”:“Coach”}Indicates that a monitoring party (role is Monitor) is currently monitoring the channel. 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 channel. The monitor can communicate with both the agent and external party.
VirtualAssistant{"result":"Abandoned"}

The Virtual Assistant did not resolve the interaction. The party working with the Virtual Assistant abandoned the interaction during the session.

VirtualAssistant{"result":"Escalated"}

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.

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

{"appletType": "MessageTake"}

Indicates the type of applet that created the voicemail recording. This could be "VoiceMail" or "MessageTake".
VoicemailRecording

{"targetAgentId": "1234"}

The ID of the agent that the voicemail was left for. This is set if the appletType was "VoiceMail".

latestUpdate

After the list of interactions, the response returns a latestUpdate parameter. The value of latestUpdate is the time of the most recent interaction event that is available using the Insights Stats API.

The difference between the current time and the 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.


Try it out

  

For information, see Trying out Vonage Contact Center APIs.