Introduction to the CCS

The Conversation Context Service (CCS) 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 CCS, you can have multiple namespaces for different business use cases. Typically, a namespace groups together related attributes. Namespaces are per account.

In Conversation Builder, there are many functions for managing data in the CCS; these are discussed in this article. The 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.

Data scopes

The Conversation Builder functions for managing data in the CCS allow you to set data in the following scopes within a namespace:

• Entity: Data set in this scope is available to the bot in any conversation (as long as you provide the entity ID).
• Conversation: Data set in this scope is only available to the bot in the current conversation.
• User: Data set in this scope is available to the bot in any conversation that includes the user.
• Global: Data set in this scope is available to the bot in any conversation. Use the globally-scoped functions only to manage data that is truly global: the data is consistent across every user and every conversation, such as your store's operating hours. Don’t use these functions to aggregate data from many different users or conversations; the functions are not designed for that purpose.

Important info for hybrid solutions

If you're using both the Conversation Builder scripting functions discussed in this article 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.

Learn about the v2 APIs.

Get started - Set up the CCS

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.

Check if the Context API is enabled

The isContextApiEnabled method checks whether the Context API is enabled.

Example

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

Register a namespace

The registerContextNamespace method creates a custom namespace.

If the namespace already exists, the method reuses it rather than creating a duplicate. While you only need to call it once per namespace, multiple calls are safe and will not result in redundant records.

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

Managing data by entity - an overview

Conversation Builder offers several scripting functions that have the flexibility to store, retrieve, and delete contextual data from the CCS using any unique identifier that’s meaningful and relevant to your brand. These functions include:

• setContextDataForEntity(namespace, entityId, name, value)
• setContextDataForEntity(namespace, entityId, properties)
• getContextDataForEntity(namespace, entityId, name)
• getContextDataForEntity(namespace, entityId)
• deleteContextDataForEntity(namespace, entityId, name)

These functions aggregate and manage data at the entity level, which is highly flexible and customizable. All of the other functions discussed elsewhere in this article manage data in the CCS at the conversation, user, or global level. Learn about data scopes.

Understanding entities

What’s an entity? An entity is something that exists as a single, distinct, and uniquely identifiable unit about which information is stored and managed.

The primary use case is the consumer about whom you want to store consumer-specific information like account balance, preference settings, loyalty status, and more. Here you can use your own brand’s internal consumer ID as the unique identifier (entityId).

But entities can also be other things, such as a product or SKU, an order, a shipment, a store or location, a device or equipment, a campaign, a ticket, etc.

Issues with other approaches

Historically, to store consumer context, brands used the setContextDataForUser function (see "Set data by user"), which relies on the user ID that’s generated by Conversational Cloud as the unique identifier. But many brands found it more useful to rely on their own internal user IDs, so they used setGlobalContextData instead (see "Set global data"), aggregating the data using the globally scoped functions. Not only were these approaches less desirable, the latter in particular yielded very large documents under the hood, opening up performance and manageability issues.

A better solution for storing consumer context is to use the setContextDataForEntity functions (see "Set data by entity"). They allow you to segregate data using your own brand's internal unique identifiers, which avoids the previous performance and manageability problems.

Data persistence

When storing data using the setContextDataForEntity functions, the properties are persisted for as long as the Time-to-Live (TTL) for the provided namespace.

Use appropriate TTL values, which renders manual deletion unnecessary. That said, we offer an entity-based delete method too.

Set data by entity

Use setContextDataForEntity to store context data for a given entity. The data is stored in Entity scope.

Example

var data = "{ \"property1\": \"value1\", \"property2\": \"value2\", \"property3\": \"value3\", \"property4\": \"value4\" }";

setting batch properties for an entity 
var result = botContext.setContextDataForEntity("airlineNamespace", "testEntity", data);
if(result) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

// setting name,value pair for and entity
var success = botContext.setContextDataForEntity("airlineTicketingBot", "testEntity", "intentThreshold", 2);
botContext.printDebugMessage("set context data for Entity: " + success);

Set data by conversation

Use setContextDataForConversation to store data in the Conversation Context Service in Conversation scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example - set a single property

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

Example 1 - set multiple properties

var data = "{ \"property1\": \"value1\", \"property2\": \"value2\", \"property3\": \"value3\", \"property4\": \"value4\" }";

var result = botContext.setContextDataForConversation("testNamespace", data);
if(result) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

Example 2 - set multiple properties

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

Example 3 - set multiple properties

var object = {
"prop1" : "value1",
"prop2": "value2"
};
var batchInsert = botContext.setContextDataForConversation("testNamespace", JSON.stringify(object));
if(batchInsert) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

Set data by user

Use setContextDataForUser to store data in the Conversation Context Service in User scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example

See the examples of setContextDataForConversation; they are similar.

Set global data

Use setGlobalContextData to store data in the Conversation Context Service in Global scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example

See the examples of setContextDataForConversation; they are similar.

Legacy approach for updating multiple variables

There’s also an older, legacy approach to updating multiple variables in the CCS at once: You can use the function for setting a single variable, which has a method signature that specifies three input parameters (not two). Essentially, you make a single API call submitting an object of key/value pairs as the third parameter. Here’s an example of the 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");
}

In turn, the post-process code for our example might look like this:

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

And the data from Bot Logs would look like this:

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

To migrate or not to migrate from the legacy approach

If you’re not already using the legacy approach, don’t adopt it. Use the functions discussed farther above because they are specifically designed and intended for updating multiple properties at once.

If you’re already using the legacy approach, we recommend that you migrate to the functions discussed farther above only if your implementation makes multiple API calls to update batches of properties. But, if your implementation only makes just a single API call (with a single set of keys), the effort to migrate to the newer functions isn’t worth the investment of time and testing.

Get data by entity

Use getContextDataForEntity to retrieve context data for a given entity.

Example

//get batch data for an entity
var getBatchData = botContext.getContextDataForEntity("airlineNamespace", "testEntity");
botContext.printDebugMessage("GET: Context Data: " + getBatchData);
botContext.printDebugMessage("GET: Specific Context value: " + getBatchData.property1);

// get a variable from entity
var value = botContext.getContextDataForEntity("airlineTicketingBot", "intentThreshold", "testEntity");
botContext.printDebugMessage("get context data for entity: " + value);

Get data by conversation

Use getContextDataForConversation to get data from the Conversation Context Service in Conversation scope.

getContextDataForConversation(namespace) returns 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 value = botContext.getContextDataForConversation("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for conversation scope: " + value);

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

Get data by user

Use getContextDataForUser to get data from the Conversation Context Service in User scope.

getContextDataForUser(namespace) returns 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 value = botContext.getContextDataForUser("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for user scope: " + value);

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

Get global data

Use getGlobalContextData to get a specific property in Global scope from the Conversation Context Service.

Example

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

Delete data by entity

Use deleteContextDataForEntity to delete context data for a given entity.

Example

var success = botContext.deleteContextDataForEntity("airlineNamespace", "testEntity", "intentThreshold");
botContext.printDebugMessage("delete context data for entity : " + success);

Delete data by conversation

Use deleteContextDataForConversation to delete data from the Conversation Context Service that is stored in Conversation scope.

Examples

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

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

Delete data by user

Use deleteContextDataForUser to delete data from the Conversation Context Service that is stored in User scope.

Example

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

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

Delete global data

Use deleteGlobalContextData to delete a specific property from the Conversation Context Service that is stored in Global scope.

Examples

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

Related articles

• For a more in-depth introducton to the Conversation Context Service and details on the Conversation Orchestrator API, see Conversation Context Service.
• New to Conversation Builder scripting functions in general? Review the introduction to scripting functions.