Response Structure

All responses to Interaction API queries are returned as JSON objects. Responses includes attributes and statistics relevant to your interaction.

ClosedClick here to see an example of basic response 
{
    "tenantId": "0e73a980-6557-11e6-b1b9-ca81484488df",
    "endTimestamp": "2017-12-07T19:27:48.405Z",
    "flowId": "f3207a30-1a2a-11e7-9873-1b92cd79a0c3",
    "customerConversationTime": 22.72,
    "customerTalkTime": 22.72,
    "interactionTime": 46.578,
    "segments": [
        {
            "endTimestamp": "2017-12-07T19:27:34.792Z",
            "interactionSegmentId": "99a96130-db84-11e7-b86d-6aa612aefe9d",
            "segmentEndType": "success",
            "segmentStartType": "interaction",
            "segmentToAgentId": "0383c270-6b93-11e6-83b4-ca81484488df",
            "startTimestamp": "2017-12-07T19:27:01.827Z",
            "segmentNumber": 0,
            "segmentTime": 32.965
        }
    ],
    "interactionId": "9998bf60-db84-11e7-9709-c2b07aa3bee9",
    "contactPoint": "+15065551234",
    "customer": "+15065551235",
    "customerSatisfactionScore": 10,
    "customerHolds": 0,
    "details": {
        "endTimestamp": "2017-12-07T19:27:48.405Z",
        "interactionId": "9998bf60-db84-11e7-9709-c2b07aa3bee9",
        "contactPoint": "+15065551234",
        "customer": "+15065551235",
        "csat": 10,
        "startTimestamp": "2017-12-07T19:27:01.827Z",
        "agents": [
            {
                "conversationStartTimestamp": "2017-12-07T19:27:10.779Z",
                "conversationEndTimestamp": "2017-12-07T19:27:34.144Z",
                "agentId": "0383c270-6b93-11e6-83b4-ca81484488df",
                "agentName": "Betty Agent",
                "dispositionId": "89c2d1d0-332d-11e6-8dd4-c88eee4d9f61",
                "dispositionName": "Issue resolved",
                "noteTitle": null
            }
        ],
        "direction": "inbound",
        "contactId": null,
        "channelType": "voice"
    },
    "startTimestamp": "2017-12-07T19:27:01.827Z",
    "ivrTime": 0.216,
    "dispositionName": "Issue resolved",
    "dispositionId": "89c2d1d0-332d-11e6-8dd4-c88eee4d9f61",
    "agents": [
        {
            "platformAgentId": 71,
            "agentWorkAccepted": true,
            "agentName": "Betty Agent",
            "agentWorkOfferTime": 7.023,
            "sessionId": "6f145920-db84-11e7-80f5-bb59d9e3b1bd",
            "interactionSegmentId": "99a96130-db84-11e7-b86d-6aa612aefe9d",
            "agentId": "0383c270-6b93-11e6-83b4-ca81484488df",
            "interactionAgentId": "9a9ebdb0-db84-11e7-816a-c7c1ef97bf27",
            "endTimestamp": "2017-12-07T19:27:34.792Z",
            "agentHandleTime": 23.365,
            "startTimestamp": "2017-12-07T19:27:03.435Z",
            "dispositionName": "Issue resolved",
            "tenantAgentId": 419,
            "agentConversationTime": 23.365,
            "dispositionId": "89c2d1d0-332d-11e6-8dd4-c88eee4d9f61",
            "queueId": "da75d1d0-686c-11e6-bab5-2a8ecd302b89",
            "agentTalkTime": 23.365,
            "agentWorkAcceptedTime": 7.023
        }
    ],
    "flowName": "Voice Flow with Script",
    "queues": [
        {
            "queueEntryLength": 1,
            "interactionSegmentId": "99a96130-db84-11e7-b86d-6aa612aefe9d",
            "agentId": "0383c270-6b93-11e6-83b4-ca81484488df",
            "platformQueueId": 40,
            "endTimestamp": "2017-12-07T19:27:10.779Z",
            "queueExitType": "success",
            "queueEntryType": "ivr",
            "interactionQueueId": "99c96c50-db84-11e7-95f3-204e8fcfa723",
            "queueType": "queue",
            "startTimestamp": "2017-12-07T19:27:02.043Z",
            "queueName": "Sales",
            "queueTime": 8.736,
            "slaTime": 8.736,
            "queueId": "da75d1d0-686c-11e6-bab5-2a8ecd302b89",
            "timeToAnswer": 8.736
        }
    ],
   "direction": "inbound",
   "channelType": "voice"
}

To provide meaningful context to the data, the JSON object is organized as follows:

  • Interaction—At the root level of the response, customer-related data is provided. Several objects are included at the root level. Each object provides contextual data, as follows:
    • Agent—Includes agent-related data. Each entry provides data from when an agent is allocated until the agent is deallocated in the interaction. There may be multiple agents involved in the interaction. For each time that an agent is allocated, a unique interactionAgentId attribute is created.
    • Queue—Each entry in this object provides queue-related data from when a customer enters a queue until an agent is allocated to their interaction. An interaction may be transferred to another queue, so there may be multiple queues listed. For each queue entry in an interaction, a new interactionQueueId attribute is created.
    • Segment—Each entry in this object provides data about the segments of the customer interaction. Segments can also be known as call legs. Segments are enumerated as follows:
      • Segment 0 starts when the interaction starts. The segment ends when the agent is deallocated. The agent is deallocated when he or she completes the interaction or transfers the interaction. The segment also ends when the interaction is abandoned or canceled. For an interaction that is not transferred and no participants are added, there is only one segment.
      • Segment 1 and subsequent segments start when the first agent transfers the interaction or a participant is added. The segment ends either when the second agent is deallocated, either by concluding the call or transferring the interaction. The segment also ends if interaction is abandoned or canceled.

Understanding Agent IDs in the Segment Object

At least one agent is involved in each segment of an interaction. If that agent transfers the interaction to another agent or adds another agent (add participant), multiple agents are identified in the segment JSON object. Each agent in a segment requires a unique ID.

You can consider agents IDs as identifying the "From Agent" and "To Agent". These terms are not used in the JSON object and only meant to explain the following agent-related IDs:

  • segmentAgentId—The "From Agent. This is the agent responsible for creating this segment. For example, this is the agent that initiated the add-participant or transfer event, or makes an outbound interaction. Segment 0 does not return a segmentAgentId parameter because an interaction-start event, not an agent, created the segment.
  • segmentToAgentId—The "To Agent". This is the agent that accepted the work, either through a transfer or add participant action, for this segment.
    • For inbound interactions, the segmentToAgentId is the UUID of the agent that accepted the transfer invitation, and therefore, is the agent associated with this segment.
    • For outbound interactions, the segmentAgentId is the UUID of the agent that initiated the outbound interaction, and therefore is the agent associated with this segment .The agent that initiated the outbound interaction is also identified as both the “From Agent” (segmentAgentId) and the “To Agent” (segmentToAgentId).

Statistic Definitions

The attributes and statistics can vary from interaction to interaction based on factors such as the channel and actions that take place within the interaction.

For more information on the statistics that are returned, see the Data Dictionary. Statistics are listed by their user-friendly name in the Data Dictionary. To search for the Interaction API name, expand the Data Dictionary and press CTRL + F to open a search box. For more information, see Online Help Search Tips.

What Happens with Parameters that have Null Values

By default, GET requests return only parameters that have a value. If the value is null, the parameter is filtered out of the response. You can run a query to return all parameters, including those with null values by appending ?green=false to your request. See Example: Including Null Values in a Response.