Get a Specific Interaction

Use a GET request to retrieve the details of a specific interaction. For example, IDs, names, timestamps, and statistics relevant to the interaction. You must have the INTERACTIONS_API_READ_ALL permission to retrieve the interaction details.

Request

 

Sample Request

curl GET https://api.cxengage.net/v1/tenants/<tenantID>/interactions/<interactionID>

Request Parameters

 This reference is a work in progress as we continuously add to it and improve it. Your response may include statistics that are not described in this reference. If you notice that the parameter that you are looking for isn't currently listed, please check back on an ongoing basis.

The table below lists and describes the parameters that you can include in the request.

ParameterDescription

tenantID

required

UUID

The tenant's unique identifier.

interactionID

required

UUID

The interaction's unique identifier.

Response

Sample Response

The request returns JSON structured like the example below:

{
    "tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
    "customerAbandonTime": 94.166,
    "endTimestamp": "2017-12-07T19:22:07.638Z",
    "flowId": "28219e00-82b6-11e7-b08f-6e56a766befb",
    "interactionTime": 94.244,
    "segments": [
        {
            "segmentNumber": 0,
            "segmentCancelled": true,
            "interactionSegmentId": "b2233520-db83-11e7-b86d-6aa612aefe9d",
            "segmentStartType": "interaction",
            "endTimestamp": "2017-12-07T19:22:07.560Z",
            "segmentEndType": "customer-disconnect",
            "segmentCancelTime": 94.166,
            "startTimestamp": "2017-12-07T19:20:33.394Z",
            "segmentTime": 94.166
        }
    ],
    "interactionId": "b2109780-db83-11e7-9709-c2b07aa3bee9",
    "contactPoint": "+15065551111",
    "customer": "+15065552222",
    "customerHolds": 0,
    "details": {
        "endTimestamp": "2017-12-07T19:22:07.638Z",
        "interactionId": "b2109780-db83-11e7-9709-c2b07aa3bee9",
        "contactPoint": "+15065551111",
        "customer": "+15065552222",
        "csat": null,
        "startTimestamp": "2017-12-07T19:20:33.394Z",
        "agents": [],
        "direction": "inbound",
        "contactId": null,
        "channelType": "voice"
    },
    "startTimestamp": "2017-12-07T19:20:33.394Z",
    "dataComplete": true,
    "ivrTime": 0.173,
    "flowName": "Basic Flow",
    "queues": [
        {
            "queueEntryLength": 1,
            "interactionSegmentId": "b2233520-db83-11e7-b86d-6aa612aefe9d",
            "queueAbandonTime": 93.993,
            "platformQueueId": 743,
            "queueAbandoned": true,
            "endTimestamp": "2017-12-07T19:22:07.560Z",
            "slaAbandoned": true,
            "queueExitType": "abandon",
            "queueEntryType": "ivr",
            "interactionQueueId": "b23cb090-db83-11e7-95f3-204e8fcfa723",
            "queueType": "queue",
            "startTimestamp": "2017-12-07T19:20:33.567Z",
            "queueName": "Support",
            "queueTime": 93.993,
            "slaTime": 93.993,
            "queueId": "3703e470-834a-11e7-b08f-6e56a766befb"
        }
    ],
    "direction": "inbound",
    "channelType": "voice"
}

Response Parameters

For an overview of the structure of the JSON response, see Response Structure.

Your response may include statistics that are not described in this reference. For more information about the statistics that are returned, see the Data Dictionary.

For each interaction, the following parameters might be returned:

ParameterDescription
tenantIDThe unique identifier of the tenant.
flagType

An interaction is flagged when CxEngage detects an abnormality in the reporting data due to an event. The flagType tells you the generic reason for why the interaction was flagged.

forced - no reason provided—The interaction was manually flagged.

Agent—The agent endTimestamp was not received/processed by reporting.

exceed-counter-limit-terminated—The interaction exceeded the counter limit.

Queue—The queue endTimestamp was not received/processed by reporting.

Stuck—The interaction endTimestamp was not received/processed by reporting.

error-uncaught-flow-error—An uncaught flow exception occurred.

null—The interaction was not flagged.

Segment—The segment endTimestamp was not received/processed by reporting.

Safeguard-terminated—The interaction reached the safeguard limit.

flaggedFlagged interactions are indicated by an exclamation mark (!) to show that these interactions may have missing data associated with them. For example, when there isn't a timestamp for when an agent left the interaction or the interaction left a queue. As a result, some of the data associated with the interaction may be inaccurate.Flagged interactions are shown in the Interaction Detail, Interaction Details by Agent, and Interaction Details by Contact reports.

end

The date and time, in UTC, that the interaction ended.
flowIdThe unique identifier of the flow.
interactionIdThe unique identifier of the interaction.
contactPointThe phone number or email address that the customer contacted.
customerThe phone number or email address of the customer.
messagingTranscriptThe transcript of the SMS conversation.
notesThe note that the agent wrote for the interaction.
startThe date and time, in UTC, that the interaction started.
audioRecordingA link to the audio recording if recording was enabled for the flow that received the interaction.
dispositionNameThe human-readable description of the disposition assigned to the interaction.
dispositionIdThe unique identifier of the disposition assigned to the interaction.
flowNameThe human-readable name of the flow.
directionThe direction of the interaction, either inbound or outbound.
contactIdThe contact's unique identifier.
channelTypeThe channel of the interaction such as voice, email, or SMS.
outboundIdentifier

The phone number, SMS number, or email address that displays to the customer when agents make an outbound interaction. The following attributes are returned:

  • interactionOutboundIdentifierID—The unique Id of the interaction outbound identifier.

  • outboundIdentifierId—The unique Id of the outbound identifier.

  • outboundIdentifierValue—The phone number or email address that displays to the customer when agents make an outbound interaction. This is based on the channelType of the interaction: voice, sms, or email.

  • outboundIdentitiferName—The description of the outbound Identifier.

hooks

If the interaction is linked with a record from a third-party Customer Relationship Manager (CRM) or ticketing system, the following attributes are returned:

  • interactionHookId—The unique identifier of hook instance.
  • hookSubType—The type of record linked to the interaction. For example, this could be user or ticket.
  • agentId—The unique identifier of the CxEngage agent.
  • hookType—The third-party application, for example, zendesk.
  • hookName—The title associated with the third-party record linked to the interaction. For example, this could be a contact name or a ticket number. This parameter might also be a custom reporting attribute.
  • hookedBy—The unique identifier for the third-party system user. For example, the Zendesk user identification for the user that linked the record to the CxEngage interaction.
  • hookId—The unique identifier of the record from the third party system that that is linked to the interaction. For example, a ticket number for Zendesk or a case number for Salesforce. This attribute is part of a three-way key that also includes hookType and hookSubtype.
  • timestamp—The date and time, in UTC, of when this interaction was linked to a third-party record.
segments

Each entry in this object provides data about the segments of the customer interaction.

The following attributes are returned for each segment:

  • segmentAgentId—Displays the ID of the agent responsible for creating this segment. For example the agent that initiated the add-participant or transfer event, or makes an outbound interaction.
  • segmentToAgentId—Displays the ID of the agent that accepted the work, either through a transfer or add participant action, for this segment.
  • interactionSegmentId—A unique identifier for the segment.
  • segmentNumber—Segments are enumerated as follows:
    • Segment 0 is always the result of an interaction-start event. The segment ends when either the agent is deallocated from the interaction or the customer abandons.
    • Segment 1 (and subsequent segments) are created as the result of a transfer-start or add-participant-start event.
  • startTimestamp—The date and time, in UTC, that the segment started.
  • segmentStartType—Displays the type of action that initiated the segment, either:
    • interaction—Indicates that the segment was initiated by an interaction-start event.
    • transfer—Indicates that a transfer event initiated the segment.
    • addParticant—Indicates that an add-participant event initiated the segment.
  • endTimestamp— The date and time, in UTC, that the segment ended.
  • segmentEndType—Displays the type of action that ended the segment.
    • interaction-end—The interaction is complete.
    • customer-disconnect—The customer abandons the interaction.
    • cancelled—The agent cancels the Add Participant or Transfer action.
    • success—An agent accepts the transfer, causing the agent that initiated the transfer to be deallocated from the interaction.
  • segmentCancelled—Displays true if the transfer was canceled or abandoned.
  • segmentCancelTime—The amount of time, in seconds, from the interaction start until the segment is cancelled, either by a customer-disconnect or cancelled event.
  • segmentTime—The amount of time, in seconds, from the interaction start until the segment is complete, either by a success or interaction-end event.
agents

Each entry in this object includes agent-related data. Each entry provides data from when an agent is allocated until the agent is deallocated in the interaction.

The following attributes are returned for each agent:

  • platformAgentId—The unique identifier of the platform user.
  • agentName—The first and last name of the agent.
  • sessionId—The unique identifier for the agent's session. A session begins when an agent logs in to Agent Toolbar or any of the Skylight products and ends when the agent logs out.
  • interactionSegmentId—A unique identifier for the segment. If an interaction enters the same queue twice in an interaction, each queue entry is given a unique identifier.
  • agentId—The unique identifier of the CxEngage agent.
  • interactionAgentId—Each agent is involved in an interaction is given a unique identifier. For each time that an agent is allocated, a unique interactionAgentId attribute is created.
  • endTimestamp—The date and time, in UTC, that the agent was deallocated from the interaction.
  • agentWorkCancelTime—

    The length of time from when the interaction is offered to the agent until:

    • The agent is deallocated during the work offer. Agent deallocation occurs when the agent disconnects during the work offer, for example, when the agent closes their browser window or shuts off their computer. It does not include when an agent actively rejects a work offer or the work offer times out.  
    • The customer disconnects before the agent either accepts or rejects the offer.

  • startTimestamp—The date and time, in UTC, that the agent was allocated to the interaction.
  • tenantAgentId—The unique identifier of the tenant user.
  • queueId—The queue's unique identifier.
queues

Each entry in this object provides queue-related data when a customer enters a queue until an agent accepts the interaction.

The following attributes are returned for each queue:

  • interactionSegmentId—A unique identifier for the segment that this enqueuement belongs to.
  • agentId—The unique identifier of the agent who accepts the interaction from the queue.
  • platformQueueId—An integer value that third-party Workforce Management (WFM) systems can use to associate with the CxEngage queue. In CxEngage, queues are identified by a UUID, so a second identification number is required for third-party systems that don't use UUIDs.
  • endTimestamp—The date and time, in UTC, that the interaction exited the queue.
  • queueExitType—The action that caused the interaction to leave the queue. Valid options are timeout, success, callback, abandon, add-participant-cancel, and interaction-end.
  • queueEntryType—The actions that put the interaction in the queue. Valid options are transfer, add participant, callback, ivr, or timeout.
  • interactionQueueId—A unique identifier for each time that an interaction enters a queue. For each queue entry in an interaction, a new interactionQueueId attribute is created.
  • queueType—The type of queue, either queue or resource.
  • startTimestamp—The date and time, in UTC, that the interaction entered the queue.
  • queueName—The human-readable name of the queue.
  • queueId—The queue's unique identifier.
dataCompleteDisplays true if the interaction is complete.