Note: Please make sure the read the overview before getting started with this method.

Description

Use this method to access the LivePerson monitoring system in order to retrieve an engagement with an updated state of availability for a consumer. The eligibility of an engagement is based on campaign definitions and possibly also on information regarding consumer activity within the brand's account, such as engagement attributes.

Use cases

  1. Obtain an engagement. An engagement will be provided if both the following apply:
    • there is no active conversation for this consumer
    • the consumer is eligible for an engagement
  1. Obtain the identifiers of an active conversation for this consumer, if one exists.

Request

Method URL
POST https://{domain}/api/account/{account-id}/app/{app-installation-id}/engagement?v={api-version}&vid={visitor-id}&sid={session-id}&obh=false

Path Parameters

Parameter Description Type Notes
account-id LP site ID string  
app-installation-id App installation id string String, Required. This is received after installing the application, as explained here

Query parameters

Parameter Description Type Required Notes
v API version number double Required Supported Value: 1.0, 1.1
vid Visitor Id String Optional Must be saved in order to reuse for future requests in the same visit
sid Session Id String Optional on first request, otherwise required Will be provided by the server-side in a 201 (CREATED) response for this specific consumer and device and should be set by the client-side on all the subsequent requests to the server
obh is On Behalf Boolean Optional possible values: true/ false (the default is false). This parameter can be used (by passing true) to let LP servers know that this request is on behalf of the visitor (and not coming from the visitor himself), so the servers should NOT update the visitor Geo-location meta-data according to this request IP

Body Parameters

Parameter Description Type Required Notes
consumerId Consumer Id (deprecated) string Optional, deprecated — use identities instead  
identities List of identities string (JSON) Optional  
identities.iss URL for domain issuer string Optional For unauth this is the csds-domain/account-id, for authenticated the brand should supply the URL
identities.acr ACR — account config read string Required for each identity Supported values: "0" for unauth, "loa1" for auth
identities.sub The subject for identification string Required  
clientProperties Optional JSON format with the following fields: Type, Platform, Name, Version, Client timestamp string Optional JSON structure — The main purpose of this information is for troubleshooting and visibility of the consumer SDK / app version that manages the communication with the server side.
clientProperties.appVersion Application version string Optional Example: For mobile it will be the host app version
clientProperties.deviceFamily   string Optional Example: personal_computer/tablet/mobile_phone
Supported values: "DESKTOP", "TABLET", "MOBILE"
clientProperties.ipAddress IP address (V4) string Optional (IP format XXX.XXX.XXX.XXX)
Validation: Real IP address (IPv4)
clientProperties.os Contains the operating system, including version info string Optional Supported values: "WINDOWS", "MAC_OSX", "LINUX", "IOS", "ANDROID"
clientProperties.osVersion OS version string Optional Example: For Android it could be 2.4
entryPoints List of entry points in the external system relevant for the engagement Comma delimited list of strings Optional Example: ["http://one.url","tel://972672626"]
engagementAttributes Array of engagement attributes string Optional Supported Values: all engagement-attributes excluding the type of ImpressionEvent (Java version inherited from ImpressionEventBase).

Security considerations

  • To avoid security problems and increase reliability, the consumerId or the sub key of the identities array (depending on which one you use) described in the table above must meet the following requirements:

    • Unguessable - using consumerID or a sub value which is based on any of the consumer's public information, such as name, email address, phone number, etc. can be guessed easily and is not recommended.

    • Innumerable - the consumerID cannot be comprised of serial numbers and must be a set of characters that have no structure, form, or scheme.

    • Unique per user - the consumerID cannot be recycled from one user to another. Do not reuse the same consumerID for more than one user, even if this user is not active anymore.

  • A good consumerID would be:

    • UUID assigned specifically and uniquely for consumer

    • a hashed/salted email address

  • For authenticated messaging flows: In order to support continuity and reporting, the consumerID must match the 'sub' claim reported inside the JWT. See Authentication → Implementation Guide for additional information on authentication.

POST Request and body entity example

Example call URL

https://{liveperson-monitor-domain}/api/account/{account-id}/app/123/engagement?v=1.0&vid=myNewVisiorId&sid=myNewSessionId

Example Body Entity

{
 "clientProperties":{
   "osName": "MAC_OSX",
   "osVersion": "1.2",
   "appVersion": "1.0",
   "deviceFamily": "MOBILE",
   "ipAddress": "192.168.5.2"
 },
 "consumerId":"uniqueIdInBrand",
 "identities": [
   {
        "iss": "LivePerson",
        "acr": "0",
        "sub": "identifierForNoAuth"
    },
    {
        "iss": "TMO",
        "acr": "loa1",
        "sub": "identifierForAuth"
    }
 ],
 "entryPoints":[
   "tel://972737004000",
   "https://www.liveperson.com/",
   "sec://Sport",
   "lang://English"
 ],
 "engagementAttributes": [
   {
     "type": "personal",
     "personal": {
       "contacts": [{"email":"user123@gmail.com","phone":"12345678"},{"email":"aaa@domain.co.il","phone":"98765430"}],
       "age": {
         "age":30.0,
         "year":1985,
         "month":7,
         "day":22
       },
       "firstname": "test",
       "lastname": "test2",
       "gender": "FEMALE",
       "company": "liveperson"
     }
   }
 ]
}

Response

Response entity examples

Status code: 201 Created — Engagement is available, created new session:

{
  "sessionId": "abc",
  "visitorId": "xyz",
  "pageId": "595933432",
  "engagementDetails": [
    {
      "campaignId": 880524023,
      "engagementId": 880524123,
      "engagementRevision": 21,
      "contextId": "1",
      "connectorId": 2642324112,
      "status": "expose"
    }
  ]
}

Status code: 200 OK — Resume conversation same session:

{
  "sessionId": "abc",
  "visitorId": "xyz",
  "pageId": "2095636278",
  "engagementDetails": [
    {
      "campaignId": 880524423,
      "engagementId": 880524523,
      "engagementRevision": 23,
      "conversationId": "fdasfdas",
      "connectorId": 2642324112,
      "status": "conversation"
    }
  ]
}

Status code: 200/201 OK — Engagement is unavailable.

Note: Because the engagement is unavailable, the engagementDetails object does not return:

{
     "sessionId": "abc",
     "visitorId": "xyz",
     "pageId": "4743822558"
}

Loading Account: API version 1.0, Status code 500 Server Error

{
    "time":1501074704502,
    "message":"Loading account: ta3hWd4IgG, vid: myVisitorId",
    "internalCode":20
}

API version 1.1, Status code 202 Accepted

{
    "time":1501074704502,
    "message":"Loading account: ta3hWd4IgG, vid: myVisitorId",
    "internalCode":38
}

Response format

Attribute Description Type Required
engagementDetails The details of an engagement when it is available object Required if there is an engagement
engagementDetails.campaignId   number Required if there is an engagement
engagementDetails.engagementId   number Required if there is an engagement
engagementDetails.conversationId   string Required if there is an open conversation
engagementDetails.windowId   string Required if there is an engagement
engagementDetails.connectorId   string Required if there is an engagement
engagementDetails.language   string Required if there is an engagement
engagementDetails.engagementRevision   number Required if there is an engagement
engagementDetails.status   string Required if there is an engagement, possible values: "expose" or "conversation" if there is an open conversation
pageId Page identification ID for sending event on the current engagement string Required
sessionId The visit session ID string Must be saved in order to reuse for future requests in the same visit
visitorId The visit visitor ID string Must be saved in order to reuse for future requests in the same visit

Response Codes

Code Description
200 OK
201 Created
202 Accepted
400 Validation error
404 Data not found
500 Internal server error
503 The server is temporarily unavailable

Retry Policy Recommendation

Error code Meaning Recommendation
4xx Client side error Do not retry, fix problems in code
5xx There was an error on server side Retry 4 times with 3, 10, 30, 90 seconds pause interval between retries
202 Loading account Retry 4 times with 3, 10, 30, 90 seconds pause interval between retries

Specifically in the case of a "Loading account" response (500 in API version 1.0, 202 in API version 1.1), it is important to retrieve the value of the vid from the response body and append it as the value of the vid query param for the retry request (to be issued following a pause interval of a few seconds).