The CONVERSATION method is a batch-endpoint (this means that one payload can contain several payloads). It takes a set of at least two JSON payloads. The order of the array is important, as the example shows, since Conversational Cloud expects to receive these payloads in that order. Returns an array of corresponding JSON payloads in the response. The most important value obtained by this endpoint is the conversationId which will be used for the following SEND calls to Conversational Cloud.

Getting Started

1. Retrieve your domain. Use the LivePerson Domain API to retrieve this information by providing the following service name:

   • asyncMessagingEnt

2. Note the API terms of use.

Request URI

Path Parameters

Query Parameters

Request Headers

Request Body

Notes:

For the JSON payload, please have a look at the Messaging Window API with its integrated Request Builder to get an example of the accepted payloads.

This method expects a set of JSON payloads, each representing a different type of request to the Conversational Cloud messaging service. The order of the payloads is important in order to create a new conversation. First, the payload with the type userprofile.SetUserProfile appears, second the payload with the type cm.ConsumerRequestConversation appears.

The payload with the type userprofile.SetUserProfile is mandatory. Its body can essentially be passed empty or with some engagement attributes in order for the Agent to see the Consumer Info in the Conversational Cloud Agent Workspace.

For the sake of simplicity, the next request body example illustrates the minimal JSON Payload which is mandatory for conversation creation in Conversational Cloud:

[
  {
  "kind": "req",
  "id": "1,",
  "type": "userprofile.SetUserProfile",
  "body": {}
  },
  {
    "kind": "req",
    "id": "2,",
    "type": "cm.ConsumerRequestConversation",
    "body": {
      "brandId": "{accountid}"
    }
  }
]

Nevertheless, we strongly recommend not to create conversations as such, as there is no user information passed in the body of the payload with type userprofile.SetUserProfile nor there is any information passed in the body of the payload with type cm.ConsumerRequestConversation that will enable targeting the conversation to the right skill or engagement in Conversational Cloud.

Passing user information is done under the authenticatedData object in the body of the payload with the type userprofile.SetUserProfile. If the authenticatedData object is not passed (left blank or deleted altogether), there will be no consumer information for the Agent to see in Conversational Cloud's Agent Workspace. Under the authenticatedData object, you can pass an lp_sdes array. This array is used to send engagement attributes (SDEs) to Conversational Cloud.

The SDEs are used to populate the consumer information for the Agent to see in Conversational Cloud's Agent Workspace. Hence, as a best practice we recommend to always pass SDEs when creating a new conversation.

The SDEs supported for sending are the Customer Info and Personal Info SDEs.

The next request body example illustrates how to create a conversation and send SDEs in one request:

[{
  "kind": "req",
  "id": "1,",
  "type": "userprofile.SetUserProfile",
   "body": {
     "authenticatedData": {
       "lp_sdes": [
         {
           "type": "ctmrinfo",
           "info": {
             "socialId": "1234567890",
             "ctype": "vip"
           }
         },
         {
           "type": "personal",
           "personal": {
             "firstname": "John",
             "lastname": "Doe",
             "gender": "MALE"
           }
         }
       ]
     }
   }
 },
	{
		"kind": "req",
		"id": "2,",
		"type": "cm.ConsumerRequestConversation",
		"body": {
			"brandId": "{accountid}"
		}
	}
]

The above request is much better as it also includes the user SDEs which will populate the consumer information in Conversational Cloud's Agent Workspace. These SDEs can also be used for to target/route the conversation to a specific skill as it was configured via internal LivePerson configuration (Houston) - i.e. routing rules. See further information and examples in here.

Note: Not best practice, please avoid this method if possible.

The best practice to target conversations to skills when using messaging is to set up campaigns. You can send the Campaign ID and Enagagement ID to Conversational Cloud in order to route the consumer conversation to the desired skill as designed by the Campaign Builder. This will also allow the Agent to see the name of your connector as the source of the conversation in the Consumer info widget:

In order to retrieve the campaign properties, you need to use the Monitoring API. This API method, Engagement, allows you to send Conversational Cloud the user information (consumerId OR the visitorId and sessionId) along with the installation Id and in return to get the engagement properties: campaignId, engagementId, visitorId, sessionId and more. See the following response example.

The connector can then use the above properties in the CONVERSATION request body payload with the type cm.ConsumerRequestConversation. See the following example to see how to do so:

Example Request Body — JSON Payload

[{
  "kind": "req",
  "id": "1,",
  "type": "userprofile.SetUserProfile",
   "body": {
     "authenticatedData": {
       "lp_sdes": [
         {
           "type": "ctmrinfo",
           "info": {
             "socialId": "1234567890",
             "ctype": "vip"
           }
         },
         {
           "type": "personal",
           "personal": {
             "firstname": "John",
             "lastname": "Doe",
             "gender": "MALE"
           }
         }
       ]
     }
   }
 },
  {
    "kind": "req",
    "id": "2,",
    "type": "cm.ConsumerRequestConversation",
    "body": {
      "ttrDefName": "NORMAL",
      "campaignInfo": {
        "campaignId": "99999",
        "engagementId": "888888"
      }, "conversationContext": {
    "visitorId": "A3ZTY3Zjk1MDExZTczYTU4",
    "sessionId": "ys2wSqaSRSOJGki7VhEDKQ",
    "interactionContextId": "2",
    "type": "SharkContext",
    "lang": "en-US"
     },
      "channelType": "MESSAGING",
      "brandId": "{accountid}",
      "skillId": "-1"
    }
  }
]

userprofile.SetUserProfile Properties

cm.ConsumerRequestConversation Properties

conversationContext Properties

Response

Response Codes

Response Example

HTTP Status Code 200 Response Format JSON

[
    {
        "code": "OK",
        "body": {
            "msg": "OK User Profile set successfully"
        },
        "reqId": "1,"
    },
    {
        "code": "OK",
        "body": {
            "conversationId": "8602832d-dce1-446b-8445-0d51f5926a42"
        },
        "reqId": "2,"
    }
]

Elements in the Response