Get a single interaction (Insights Stats API)

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

Headers

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

Authorization scopes supported:

Parameters

The endpoint accepts the following path parameter:

guid

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",
  "outcome":"Handled by agent",
  "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.
• 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:
  • 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.
• 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:
  • Callback connected. An outbound call from an agent to an external contact started and the external contact answered. The outbound call was initiated due to a callback request being routed to the agent.
  • Callback not connected. An outbound call from an agent to an external contact started, but the external contact did not answer. The outbound call was initiated due to a callback request being routed to the agent.
  • Callback failed. An outbound call from an agent to an external contact started, but the connection failed. The outbound call was initiated due to a callback request being routed to the agent.
  • Outbound connected. An outbound interaction from an agent to an external contact started and the external contact accepted. 
  • Outbound not connected. An outbound interaction from an agent to an external contact started, but the external contact did not accept.
  • Outbound failed. An outbound interaction from an agent to an external contact started, but the connection failed.
  • Handled by agent. An inbound interaction from an external contact connected to at least one agent.
  • Handled by CCR. An inbound interaction from an external contact connected to another external contact through a Call Connect Router applet.
  • Abandoned in queue. An external contact on an inbound interaction ended the interaction while waiting in a queue.
  • Message taken. An external contact on an inbound interaction ended the interaction after leaving either a personal or group voicemail.
  • Abandoned in bot. An external contact on an inbound interaction ended the interaction while connected to a bot.
  • Callback requested. A callback was requested by an external contact while connected to a bot. The interaction ends.
  • Callback request delivered. A callback request was delivered to, and accepted by, an agent. An outbound call to the external contact who requested the callback starts. Note that this does not indicate a successful callback. The subsequent outbound call may have an outcome of callback connected, callback failed, or callback not connected.
  • Callback request abandoned in bot. A callback request was abandoned while connected to a bot and no outbound call from an agent to the external contact was initiated. Note that this commonly occurs due to a queue breakout abandoning the queuing callback request.
  • Internal connected. An internal interaction from an agent to another agent started and the recipient agent accepted.
  • Internal not connected. An internal interaction from an agent to another agent started and the recipient agent did not accept.
  • Unknown. No interaction outcome criteria were met.
• 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:
      • 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 Resolved, Escalated or Abandoned. The messageCount property indicates the total number of sent and received messages.

      • 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:

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.