Example: Searching Interactions for Specific Third-party System

This example demonstrates how to use a GET request to retrieve interactions that are linked to Zendesk ticket records.

Request

Sample Request

The request below returns a list of interactions that are linked to a specific Zendesk ticket:

curl GET https://api.cxengage.net/v1/tenants/0e73a980-6557-11e6-b1b9-ca81484488df/interactions?hookType=zendesk&hookSubType=ticket&hookId=26359162568

Request Parameters

The table below lists the parameters you can include in a request:

Parameter Required? Type Description
tenantId yes UUID The tenant's unique identifier.
type no string Type zendesk.
hookSubType no string Type ticket.

Response

Sample Response

The request returns JSON structured like the example below:

{
    "tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
    "limit": 10,
    "offset": 0,
    "tenantName": "Your Tenant",
    "page": null,
    "hookSubType": "ticket",
    "total": 1,
    "tenantTimezone": "US/Eastern",
    "results": [
        {
            "tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
            "hooks": [
                {
                    "interactionHookId": "ccf42b31-c557-11e7-9c00-e7ff9ff8d805",
                    "hookSubType": "ticket",
                    "agentId": "e05468e0-82b1-11e7-b08f-6e56a766befb",
                    "hookType": "zendesk",
                    "hookedBy": "26303434627",
                    "hookId": "415",
                    "timestamp": "2017-11-09T14:10:54.947Z"
                },
                {
                    "interactionHookId": "e2494a11-c557-11e7-9c00-e7ff9ff8d805",
                    "hookSubType": "user",
                    "agentId": "e05468e0-82b1-11e7-b08f-6e56a766befb",
                    "hookType": "zendesk",
                    "hookName": "Bob Jones",
                    "hookedBy": "26303434627",
                    "hookId": "26359162568",
                    "timestamp": "2017-11-09T14:11:30.737Z"
                }
            ],
            "endTimestamp": "2017-11-09T14:12:05.323Z",
            "flowId": "28219e00-82b6-11e7-b08f-6e56a766befb",
            "customerConversationTime": 102.243,
            "customerTalkTime": 102.243,
            "interactionTime": 109.604,
            "segments": [
                {
                    "endTimestamp": "2017-11-09T14:13:07.077Z",
                    "interactionSegmentId": "b5927370-c557-11e7-9c00-e7ff9ff8d805",
                    "segmentEndType": "success",
                    "segmentStartType": "interaction",
                    "segmentToAgentId": "e05468e0-82b1-11e7-b08f-6e56a766befb",
                    "startTimestamp": "2017-11-09T14:10:15.719Z",
                    "segmentNumber": 0,
                    "segmentTime": 171.358
                }
            ],
            "interactionId": "0d8b3d92-5f24-4ffa-8bbe-cb4aca4240d9",
            "contactPoint": "+15065551111",
            "customer": "+15065552222",
            "customerHolds": 0,
            "startTimestamp": "2017-11-09T14:10:15.719Z",
            "ivrTime": 1.138,
            "dispositionName": "Issue resolved",
            "dispositionId": "89c2d1d0-332d-11e6-8dd4-c88eee4d9f61",
            "agents": [
                {
                    "platformAgentId": 15184,
                    "agentWorkAccepted": true,
                    "agentName": "Kris Agent",
                    "agentWorkOfferTime": 2.725,
                    "agentWrapUpTime": 61.712,
                    "sessionId": "05200a00-c554-11e7-8aba-0fc9cd50d3ff",
                    "interactionSegmentId": "b5927370-c557-11e7-9c00-e7ff9ff8d805",
                    "agentId": "e05468e0-82b1-11e7-b08f-6e56a766befb",
                    "interactionAgentId": "b79e4900-c557-11e7-b5e2-9a5ac3da6edd",
                    "endTimestamp": "2017-11-09T14:13:07.077Z",
                    "agentHandleTime": 164.262,
                    "startTimestamp": "2017-11-09T14:10:19.152Z",
                    "dispositionName": "Issue resolved",
                    "tenantAgentId": 8376,
                    "agentConversationTime": 102.55,
                    "dispositionId": "89c2d1d0-332d-11e6-8dd4-c88eee4d9f61",
                    "queueId": "3703e470-834a-11e7-b08f-6e56a766befb",
                    "agentTalkTime": 102.55,
                    "agentWorkAcceptedTime": 2.725
                }
            ],
            "flowName": "Basic Flow",
            "queues": [
                {
                    "queueEntryLength": 1,
                    "interactionSegmentId": "b5927370-c557-11e7-9c00-e7ff9ff8d805",
                    "agentId": "e05468e0-82b1-11e7-b08f-6e56a766befb",
                    "platformQueueId": 743,
                    "endTimestamp": "2017-11-09T14:10:22.129Z",
                    "queueExitType": "success",
                    "queueEntryType": "ivr",
                    "interactionQueueId": "b5a697b0-c557-11e7-a497-576bd37493df",
                    "queueType": "queue",
                    "startTimestamp": "2017-11-09T14:10:16.857Z",
                    "queueName": "Support",
                    "queueTime": 5.272,
                    "slaTime": 5.272,
                    "queueId": "3703e470-834a-11e7-b08f-6e56a766befb",
                    "timeToAnswer": 5.272
                }
            ],
            "direction": "inbound",
            "channelType": "voice"
        }
    ]
}
}

Response Parameters

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.

The table below lists and describes the parameters that can be returned in the response.

Parameter Description
page The page number for the page of results returned in the request.
limit The number of interactions to return per page. The default is 10. The maximum is 1000.
offset The offset, if specified, from the request. For example, the request might show interactions from page 10.
tenantId The tenant’s unique identifier.
total The number of interactions on the tenant.
tenantTimeZone The human readable name of the time zone for the tenant.
results

For each interaction, the following parameters might be returned:

Parameter Description
tenantID The unique identifier of the tenant.
flagged Flagged interactions may have missing data associated with them. Valid values are true or null.
endTimestamp The date and time, in UTC, that the interaction ended.
flowId The unique identifier of the flow.
interactionId The unique identifier of the interaction..
contactPoint The phone number or email address that the customer contacted.
customer The phone number or email address of the customer.
messagingTranscript The transcript of the SMS conversation.
notes The note that the agent wrote for the interaction.
startTimestamp The date and time, in UTC, that the interaction started.
audioRecording A link to the audio recording if recording was enabled for the flow that received the interaction.
dispositionName The human-readable description of the disposition assigned to the interaction.
dispositionId The unique identifier of the disposition assigned to the interaction.
flowName The human-readable name of the flow.
direction The direction of the interaction, either inbound or outbound.
contactId The contact's unique identifier.
channelType The channel of the interaction such as voice, email, or SMS.
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.
  • 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.
  • 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 unique identifier of the queue that the work offer is accepted from.
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 identfied 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 unique identifier of the queue that the work offer is accepted from.