Example: Searching Interactions by a Specific Custom Reporting Attribute

This example demonstrates how to use a GET request to retrieve interactions that include a specific custom reporting attribute. Custom reporting attributes are defined in a flow using the Custom Reporting Attribute notation and stored in the hook-name parameter. To search interactions by a custom reporting attribute, you can use either the hook-name or attribute-value parameters in the query.

You can search on multiple custom reporting attributes. When you use more than one query in the search string, the REST API only returns interactions that match both queries.

Request

Sample Request

The request below returns interactions for the specified contact:

curl GET https://api.cxengage.net/v1/tenants/0e73a980-6557-11e6-b1b9-ca81484488df/interactions?attribute-value=<attributeValue>

Request Parameters

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

Parameter	Required?	Type	Description
tenantId	yes	UUID	The tenant's unique identifier.
attributeValue	yes	UUID	The value for the custom attribute.

Response

Sample Response

The request returns JSON structured like the example below:

{
    "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
    "interactionAttributes": [
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "d9f18a60-dc50-11e8-ae11-dad54383b88d",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "valueTwo",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:03.134Z",
            "hookType": "unattachedAttr",
            "interactionHookId": "d905f1e0-dc50-11e8-9eb7-c23298e321eb"
        },
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "da8dca60-dc50-11e8-ae11-dad54383b88d",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "valueOne",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:03.131Z",
            "hookType": "customAttributeWithResource",
            "interactionHookId": "d9057cb0-dc50-11e8-9eb7-c23298e321eb"
        },
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "ec6cfc60-dc50-11e8-ae11-dad54383b88d",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "1234567",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:32.863Z",
            "hookType": "customAttributeUsingIvrInput ",
            "interactionHookId": "eabe3af0-dc50-11e8-9eb7-c23298e321eb"
        }
    ],
    "hooks": [
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "d9f18a60-dc50-11e8-ae11-dad54383b88d",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "valueTwo",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:03.134Z",
            "hookType": "unattachedAttr",
            "interactionHookId": "d905f1e0-dc50-11e8-9eb7-c23298e321eb"
        },
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "da8dca60-dc50-11e8-ae11-dad54383b88d",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "valueOne",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:03.131Z",
            "hookType": "customAttributeWithResource",
            "interactionHookId": "d9057cb0-dc50-11e8-9eb7-c23298e321eb"
        },
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "hookId": "ec6cfc60-dc50-11e8-ae11-dad54383b88d",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "hookBy": "flow",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "hookName": "1234567",
            "hookSubType": "interaction-attribute",
            "timestamp": "2018-10-30T14:34:32.863Z",
            "hookType": "customAttributeUsingIvrInput ",
            "interactionHookId": "eabe3af0-dc50-11e8-9eb7-c23298e321eb"
        }
    ],
    "endTimestamp": "2018-10-30T14:34:33.166Z",
    "flowId": "95bc80c0-59e2-11e8-a331-9e78b32c710f",
    "customerConversationTime": 29.701,
    "customerTalkTime": 29.701,
    "interactionTime": 47.212,
    "segments": [
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "segmentNumber": 0,
            "interactionSegmentId": "cec87c20-dc50-11e8-9eb7-c23298e321eb",
            "segmentStartType": "interaction",
            "segmentToAgentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "endTimestamp": "2018-10-30T14:34:33.402Z",
            "segmentEndType": "success",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "startTimestamp": "2018-10-30T14:33:45.954Z",
            "segmentTime": 47.448
        }
    ],
    "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
    "contactPoint": "+15063002967",
    "customer": "+15066072058",
    "customerHolds": 0,
    "details": {
        "endTimestamp": "2018-10-30T14:34:33.166Z",
        "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
        "contactPoint": "+15063002967",
        "customer": "+15066072058",
        "startTimestamp": "2018-10-30T14:33:45.954Z",
        "agents": [
            {
                "conversationStartTimestamp": "2018-10-30T14:34:03.014Z",
                "conversationEndTimestamp": "2018-10-30T14:34:32.848Z",
                "resourceId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
                "agentName": "Ryan Boyce",
                "noteTitle": "Example Note Title"
            }
        ],
        "direction": "inbound",
        "contactId": "f4895fe0-6714-11e7-9259-cb127bd0d17b",
        "channelType": "voice"
    },
    "notes": [
        {
            "noteId": "e2f65910-dc50-11e8-9f0e-21353d459805",
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "title": "Example Note Title",
            "body": "Example Note Body",
            "created": "2018-10-30T14:34:19.000Z",
            "updated": "2018-10-30T14:34:27.000Z"
        }
    ],
    "startTimestamp": "2018-10-30T14:33:45.954Z",
    "ivrTime": 10.469,
    "agents": [
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "platformAgentId": 471,
            "agentWorkAccepted": true,
            "agentName": "Ryan Boyce",
            "agentWorkOfferTime": 5.125,
            "conversationEndTimestamp": "2018-10-30T14:34:32.848Z",
            "sessionId": "b71dd480-dc50-11e8-801c-016c5936a3b5",
            "interactionSegmentId": "cec87c20-dc50-11e8-9eb7-c23298e321eb",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "conversationStartTimestamp": "2018-10-30T14:34:03.014Z",
            "interactionAgentId": "d5cf57f0-dc50-11e8-9b97-f353dfbfdfa9",
            "endTimestamp": "2018-10-30T14:34:33.402Z",
            "talkTimes": [
                {
                    "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
                    "interactionAgentTalkTimeId": "2b833654-aeb7-5b71-91af-35c1b66e286c",
                    "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
                    "interactionAgentId": "d5cf57f0-dc50-11e8-9b97-f353dfbfdfa9",
                    "endTimestamp": "2018-10-30T14:34:33.375Z",
                    "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
                    "startTimestamp": "2018-10-30T14:34:03.014Z",
                    "queueId": "ae708610-6592-11e7-9259-cb127bd0d17b",
                    "agentTalkTime": 30.361
                }
            ],
            "agentHandleTime": 29.834,
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "agentFocusTime": 30.689,
            "startTimestamp": "2018-10-30T14:33:57.743Z",
            "tenantAgentId": 486,
            "agentConversationTime": 29.834,
            "queueId": "ae708610-6592-11e7-9259-cb127bd0d17b",
            "agentTalkTime": 29.834,
            "agentWorkAcceptedTime": 5.125
        }
    ],
    "flowName": "Custom Attributes",
    "queues": [
        {
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "queueEntryLength": 1,
            "interactionSegmentId": "cec87c20-dc50-11e8-9eb7-c23298e321eb",
            "agentId": "eaff3f40-658d-11e7-9259-cb127bd0d17b",
            "platformQueueId": 265,
            "endTimestamp": "2018-10-30T14:34:03.014Z",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "queueExitType": "success",
            "queueEntryType": "ivr",
            "interactionQueueId": "d505ed70-dc50-11e8-96a8-3d6bfcf7af8f",
            "queueType": "queue",
            "startTimestamp": "2018-10-30T14:33:56.423Z",
            "queueExitLength": 0,
            "queueName": "Support",
            "queueTime": 6.591,
            "slaTime": 6.591,
            "queueId": "ae708610-6592-11e7-9259-cb127bd0d17b",
            "timeToAnswer": 6.591
        }
    ],
    "direction": "inbound",
    "contactId": "f4895fe0-6714-11e7-9259-cb127bd0d17b",
    "customerTalkTimes": [
        {
            "interactionCustomerTalkTimeId": "d9079f90-dc50-11e8-9eb7-c23298e321eb",
            "interactionId": "c506eb9b-f523-4616-8839-fbce3fd89c17",
            "tenantId": "87165f24-f1d4-4b2e-acec-05ac94e0ead4",
            "startTimestamp": "2018-10-30T14:34:03.146Z",
            "endTimestamp": "2018-10-30T14:34:32.847Z",
            "customerTalkTime": 29.701
        }
    ],
    "channelType": "voice"
}

Response 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 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 unique identifier of the tenant.

total

The number of interactions on the tenant.

tenantTimeZone

The tenant's timezone, in TZ database format. This consists of a continent/city pair - for example, US/Central.

results

For each interaction, the following parameters might be returned:

Parameter	Description
tenantID	The unique identifier of the tenant.
flagged	Flagged 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.
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.
start	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. 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.