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

2. Obtain the identifiers of an active conversation for this consumer, if one exists.

Request

Path Parameters

Query parameters

Body Parameters

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

Response Codes

Retry Policy Recommendation

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).