Please note that this particular method of the Data Access API relates to LivePersons legacy chat product which receives limited support and will be deprecated in the future.

Engagement retrieves all engagement data in .zip format files. The engagement data consists of information about the different engagements the visitor was involved with. This includes conversation metadata (start/end time, start/end reason etc.), transcript, MCS, transfer information, and more.

Request

Method URL
GET https://{domain}/data_access_le/account/{accountID}/le/engagement?startTime=&endTime=

URL Parameters

Required:

Parameter Description Type / Value
startTime Start time in milliseconds, refers to the start time boundary of the range the files were generated. Should be used as an incremental timestamp. numeric
endTime End time in milliseconds, refers to the start time boundary of the range the files were generated. Should be used as an incremental timestamp. numeric

Response

JSON Example

Request for account 75555851:


    {
        "dataAccessFiles": {
            "@id": "75555851",
            "link": {
                "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement",
                "@rel": "self"
            },
            "file": [
                {
                    "@name": "Engagement.1467853200000.1467856800000.part-00000-0.gz",
                    "@scopeStartDate": "2016-07-06T21:00:00-04:00",
                    "@scopeEndDate": "2016-07-06T22:00:00-04:00",
                    "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement/Engagement.1467853200000.1467856800000.part-00000-0.gz"
                },
                {
                    "@name": "Engagement.1469610000000.1469613600000.part-00000-0.gz",
                    "@scopeStartDate": "2016-07-27T05:00:00-04:00",
                    "@scopeEndDate": "2016-07-27T06:00:00-04:00",
                    "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement/Engagement.1469610000000.1469613600000.part-00000-0.gz"
                }
            ]
        }
    }
    {
        "dataAccessFiles": {
            "@id": "75555851",
            "link": {
                "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement",
                "@rel": "self"
            },
            "file": [
                {
                    "@name": "Engagement.1467853200000.1467856800000.part-00000-0.gz",
                    "@scopeStartDate": "2016-07-06T21:00:00-04:00",
                    "@scopeEndDate": "2016-07-06T22:00:00-04:00",
                    "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement/Engagement.1467853200000.1467856800000.part-00000-0.gz"
                },
                {
                    "@name": "Engagement.1469610000000.1469613600000.part-00000-0.gz",
                    "@scopeStartDate": "2016-07-27T05:00:00-04:00",
                    "@scopeEndDate": "2016-07-27T06:00:00-04:00",
                    "@href": "https://va-a.da.liveperson.net/data_access_le/account/75555851/le/engagement/Engagement.1469610000000.1469613600000.part-00000-0.gz"
                }
            ]
        }
    }

Elements in the Response

Parameter Description Type / Value  
id LivePerson account number. string  
file List of files. array container  
name Name of file. string  
scopeStartDate Start time of the automated process that generates the file. ISO standard  
scopeEndDate End time of the automated process that generates the file. ISO standard
href URI to retrieve the file. string  

Data Structure

JSON Example

    {
        "dataType": {
            "com.liveperson.dataaccess.DataTypeEnum": "Engagement"
        },
        "metaData": {
            "accountId": {
                "string": "75555851"
            },
            "schemaVersion": "1.0.0.22",
            "startTime": {
                "long": 1469469281856
            },
            "endTime": {
                "long": 1469469906147
            }
        },
        "recordCollection": [
            {
                "body": {
                    "com.liveperson.dataaccess.EngagementData": {
                        "header": {
                            "com.liveperson.dataaccess.VisitorHeader": {
                                "visitId": {
                                    "string": ""
                                },
                                "visitorId": {
                                    "string": ""
                                },
                                "contextId": {
                                    "string": ""
                                }
                            }
                        },
                        "engagements": {
                            "array": [
                                {
                                    "com.liveperson.dataaccess.Conversation": {
                                        "type": {
                                            "com.liveperson.dataaccess.ConversationType": "LIVE_CHAT"
                                        },
                                        "conversationId": {
                                            "string": "755558514295264942"
                                        },
                                        "conversationStartTime": {
                                            "long": 1469469281856
                                        },
                                        "interactionStartTime": {
                                            "long": 1469469368565
                                        },
                                        "conversationEndTime": {
                                            "long": 1469469894169
                                        },
                                        "consumerId": null,
                                        "isInteractive": {
                                            "boolean": false
                                        },
                                        "sourceOrigin": {
                                            "string": "Web"
                                        },
                                        "sourceDevice": null,
                                        "endReasonId": {
                                            "int": 205
                                        },
                                        "campaignData": null,
                                        "skills": {
                                            "array": [
                                                3
                                            ]
                                        },
                                        "startReasonId": {
                                            "int": 0
                                        },
                                        "startPage": null,
                                        "startUrl": null,
                                        "transcripts": {
                                            "array": [
                                                {
                                                    "text": {
                                                        "string": "Welcome to LivePerson! A representative will be with you shortly."
                                                    },
                                                    "timestamp": {
                                                        "long": 1469469281857
                                                    },
                                                    "by": {
                                                        "string": "info"
                                                    },
                                                    "type": {
                                                        "string": "2"
                                                    },
                                                    "controlType": {
                                                        "string": "4"
                                                    },
                                                    "agentId": {
                                                        "string": "0"
                                                    },
                                                    "contentFormat": {
                                                        "string": "Text"
                                                    },
                                                    "messageId": {
                                                        "string": "S4uqCX7MQuWB1_Y1GjsVjQ"
                                                    },
                                                    "dialogId": null,
                                                    "fileData": null,
                                                    "linkData": null,
                                                    "mcs": null
                                                }
                                            ]
                                        },
                                        "transfers": {
                                            "array": []
                                        },
                                        "secureForms": {
                                            "array": []
                                        },
                                        "mcs": null,
                                        "queueStartTime": {
                                            "long": 1469469281856
                                        },
                                        "queueEndTime": {
                                            "long": 1469469368565
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }
            }
        ]
    }

Header

Parameter Description Type / Value
visitId Unique visitor session identifier. string
visitorId Unique visitor identifier. string
contextId Context ID. string

The following table describes the information that is available for engagement data:

Parameter Description Type / Value
engagements List of conversation / content entities. array container

Conversation

Parameter Description Type / Value
type Type of conversation, can be one of the following: LIVE_CHAT, MESSAGING. conversation Type
conversationId Unique conversation identifier. string
conversationStartTime Start time of the conversation (enter queue time). long
interactionStartTime Interaction start time (connection time). long
conversationEndTime End time of the conversation. long
consumerId Unique consumer identifier. string
isInteractive Indication whether the conversation is interactive (visitor wrote a line). boolean
sourceOrigin Source of conversation. string
sourceDevice Source device of the conversation, can be one of the following: NA, DESKTOP, TABLET, MOBILE. DeviceType
endReasonId Conversation end reason ID, can be any of the following:
101 — Transfer — rep stopped chat (rep transferred chat to another rep)
106 — Transfer — Reassignment to skill (rep transferred chat to skill)
201 — Rep stopped chat
202 — Rep disconnected
205 — Visitor disconnected
208 — Visitor was no longer in chat
210 — Visitor closed chat
int
campaignData Contains information about the conversation. container
agentId Unique Identifier of the conversation’s last agent. string
skillID Unique Identifier of the conversation’s last skill. long
StartReasonId Conversation’s start reason ID, can be one of the following: 0 — visitor request, 2 — transfer, 3 — transfer failed. int
startPage The page title from which the conversation started. string
startUrl The page URL from which the conversation started. string
transcripts Transcript data of the conversation. array[Message]
transfers List of transfers in the conversations. array[Transfer]
secureForms List of secure forms in the conversation. array[SecureForm]
mcs Contains information about MCS (Meaningful Conversation Score) of the conversation. MCS
queueStartTime Time when visitor requested to start conversation. long
queueEndTime Time when visitor connected to an agent. long

Message

Parameter Description Type / Value
text The text content of the message. string
timestamp Time when the message was published. long
by The name of the entity that published the message. Name of the visitor, agent’s nickname or "info" in case it is a control message. string
type The type of message. Can be one of the following: 0-VISITOR_LINE, 1 — REP_LINE, 2 -CONTROL_LINE, 3 — REP_URL_LINE, 4 — REP_HTML_LINE, 5 — REP_COMMENT_LINE. string
controlType Type of predefined content. string
agentId The ID of the agent who published the message. string
contentFormat Message content type. Possible options: NA, TEXT_PLAIN, IMG, TEXT_HTML, LINK, HOSTED_FILE. string
messageId Unique message identifier. string
dialogId ID of the dialog within the conversation. string
fileData Contains information about file data. Container- FileData
linkData Contains information about link data. Container — LinkData
mcs Contains information about MCS of the message. Container — MCS

CampaignData

Parameter Description Type / Value
campaignId Unique campaign identifier. long
campaignEngagementId Unique campaign engagement identifier. long

FileData (relevant for messaging — not supported)

Parameter Description Type / Value
caption Optional explanatory text attached to the file string
fileType Type of file. Supported types: JPG, PNG, GIF, TXT, PDF string

LinkData (relevant for messaging — not supported)

Parameter Description Type / Value
externalFileLink File location on the web. string
fileType Type of file, supported types: JPG, PNG, GIF, TXT, PDF. string
caption Optional free text attached to the file. string

Transfer

Parameter Description Type / Value
timestamp Timestamp of the transfer. string
skillId ID of the current skill. long
targetSkillId ID of the target skill ID. long
agentId ID of the current agent. string
targetAgentId ID of the target agent ID. string
agentId The ID of the agent who published the message. string
reason Reason for the transfer. long
queueStartTime Enter queue time (in transfer). long
queueEndTime Exit queue time (in transfer). long