The Conversation Context Service is a cloud-based repository for storing and retrieving session state attributes, so they can be used throughout the conversational journey. This allows for continuity in conversations as context can be transferred between agents and bots, enabling a warm hand-off. The attributes are stored as key/value pairs.

Within the Conversation Context Service, you can have multiple namespaces for different business use cases. Typically, a namespace groups together related attributes. Namespaces are per account.

In LivePerson Conversation Builder, the following built-in functions for managing the Conversation Context Service are available. These functions are synchronous, server-side, JavaScript calls that conveniently wrap the APIs in Conversation Orchestrator, LivePerson's AI engine.

All update operations return a Boolean status. It is the bot developer's responsibility to ensure the operation was executed successfully.

For a more in-depth introducton to the Conversation Context Service and details on the Conversation Orchestrator API, see Conversation Context Service.

New to scripting functions? Please review the Introduction.

Get started - Set up the Conversation Context Service

To enable the Conversation Context Service API for your account:

1. Access the Bot Accounts application, and click the organization name.
2. Turn on the Conversation Context Service toggle.
3. Do the following:
   • Use Conversational Cloud Site ID: Always select this. Then enter your site ID (account ID).
   • Use Conversation Builder Account ID: Don't select this. This option will be removed in the future.

Conversation Builder data scopes

The built-in methods support setting data in the Conversation Context Service in the following Conversation Builder scopes within a namespace:

• Global: Data set in this scope is available to the bot in all conversations.
• User: Data set in this scope is available to the user. Once it is set, it is available in all conversations for the same user.
• Conversation: Data set in this scope is only available in the current conversation.

Is the Context API enabled?

The isContextApiEnabled method checks whether the Context API is enabled.

Example

var success = botContext.isContextApiEnabled();
botContext.printDebugMessage("context API enabled: " + success);

Important info for hybrid solutions

If you're using both the Conversation Builder scripting functions discussed below and direct use of the CCS APIs, be aware that the Conversation Builder functions invoke the CCS v2 APIs indirectly. That is, they invokes the v1 APIs, which forward the requests to the v2 APIs. In such cases, when no session is provided, a session named __default__ is defined and forwarded to the v2 APIs.

If you're managing the CCS via only the Conversation Builder scripting functions, the above info isn't relevant. But in a hybrid solution, it's important to know.

Register a namespace

The registerContextNamespace method creates a custom namespace.

If the namespace already exists, this method does not create an additional one. It uses the existing namespace.

Example

var success = botContext.registerContextNamespace("airlineTicketingBot", 10800);
botContext.printDebugMessage("Register Namespace: " + success);

Delete a namespace

The deleteContextNamespace method deletes a custom namespace.

It is not mandatory to delete a previously registered namespace.

Example

var success = botContext.deleteContextNamespace("airlineTicketingBot");
botContext.printDebugMessage("Delete Namespace: " + success);

Set a variable

setGlobalContextData, setContextDataForUser and setContextDataForConversation set a variable in the Conversation Context Service at three, different Conversation Builder scopes.

Examples

var success = botContext.setGlobalContextData("airlineTicketingBot", "intentThreshold", 2);
botContext.printDebugMessage("set context data for global scope: " + success);

var success = botContext.setContextDataForUser("airlineTicketingBot", "intentThreshold", 2);
botContext.printDebugMessage("set context data for user scope: " + success);

var success = botContext.setContextDataForConversation("airlineTicketingBot", "intentThreshold", 2);
botContext.printDebugMessage("set context data for conversation scope: " + success);

Need to set a bunch of variables in the Conversation Context Service, so you can use them to guide the bot flow? Use the approach below as a best practice. It makes a single API call submitting an object of key/value pairs, as opposed to multiple API calls passing a single key/value pair. A batch approach can avoid breaching the JavaScript timeout restriction within the bot’s pre/post-process code block.

Pre-process code

var batchInsert = botContext.setContextDataForConversation("testNamespace", "batchInsert", {
  property1 : "value1",
  property2 : "value2",
  property3 : "value3",
  property4 : "value4"
});
if (batchInsert) {
   botContext.printDebugMessage("Successfully inserted batch property");
 }else{
botContext.printDebugMessage("Failed inserting batch property");
}

Post-process code

var getBatchData = botContext.getContextDataForConversation("testNamespace", "batchInsert");
botContext.printDebugMessage("GET: Context Data: " + getBatchData);
botContext.printDebugMessage("GET: Specific Context value: " + getBatchData.property1);

Data from Bot Logs

Botcontext - debug message from interaction: COLLECT_PHONE_NUMBER, javascript code: POST_PROCESS, message:GET: Context Data: {property1=value1, property2=value2, property3=value3, property4=value4}

Botcontext - debug message from interaction: COLLECT_PHONE_NUMBER, javascript code: POST_PROCESS, message:GET: specific value: value1

Get a variable

getGlobalContextData, getContextDataForUser and getContextDataForConversation get a variable from the Conversation Context Service at three, different Conversation Builder scopes.

Examples

var value = botContext.getGlobalContextData("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for conversation scope: " + value);

var value = botContext.getContextDataForUser("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for user scope: " + value);

var value = botContext.getContextDataForConversation("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for conversation scope: " + value);

Get all variables

getContextDataForUser and getContextDataForConversation get all variables in a namespace in the Conversation Context Service at two, different Conversation Builder scopes.

Both methods return a java.util.HashMap. To retrieve a specific property, use the keySet method on the returned object, like is done in the following:

function displayAllVars(map) {
  var stringOfMap = map.toString();

  for each (var i in map.keySet()) {

       botContext.printDebugMessage('Key → ' + i);
       botContext.printDebugMessage('Value → ' + map[i]);
  }
}

Examples

var valuesMap = botContext.getContextDataForUser("airlineTicketingBot");
botContext.printDebugMessage("get context data for user scope: " + valuesMap);

var valuesMap = botContext.getContextDataForConversation("airlineTicketingBot");
botContext.printDebugMessage("get context data for conversation scope: " + valuesMap);

Delete a variable

deleteGlobalContextData, deleteContextDataForUser and deleteContextDataForConversation delete a variable from the Conversation Context Service at three, different Conversation Builder scopes.

Examples

var success = botContext.deleteGlobalContextData("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

var success = botContext.deleteContextDataForUser("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

var success = botContext.deleteContextDataForConversation("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

Delete all variables

deleteAllContextDataForUser and deleteAllContextDataForConversation delete all variables in a namespace from the Conversation Context Service at two, different Conversation Builder scopes.

Examples

var success = botContext.deleteAllContextDataForUser("airlineTicketingBot");
botContext.printDebugMessage("delete all context data for user scope: " + success);

var success = botContext.deleteAllContextDataForConversation("airlineTicketingBot");
botContext.printDebugMessage("delete all context data for conversation scope: " + success);