Global Helper Functions are recommended and useful for building bots that involve any coding logic that must take place in Pre/Post-Process code or in integrations. This bot template contains a set of recommended global functions that can help to capture needed information and process common methods without the need to write the botContext methods in your bot.

This bot template serves to demonstrate the functionality of many of these global functions. It is not intended for use as a stand-alone bot, but instead as an example of how you might use these functions within your own.

Included items

Dialogs

  • 01 Welcome: Greets the user and presents them with the main menu.
  • 02 Bot Variables: Demonstrates getting the most recent user message and setting of bot variables.
  • 03 Context Session Store: Demonstrates setting and retrieving values with the Context Session Store.
  • 04 Navigation and Sending Messages: Demonstrates using code to navigate between different interactions and sending messages.
  • 05 Logging and Debugging: Demonstrates printing debug messages and logging custom events.
  • 06 Navigating Back: Demonstrates the “trail” function to keep a record of visited interactions.
  • 06B Go Back: Demonstrates the “previous()” function to revisit interactions stored using the “trail()” function.
  • 99 Fallback: This is displayed when the user enters an utterance that is not recognized.

Global Functions

The functions are designed to simplify the use of pre/post process code. All functions are provided with the dialog template.

Retrieving user message and intent

getUserMessage: Retrieves the most recent message sent to the bot.

function getUserMessage(){return botContext.getCurrentUserMessage();}

getIntent: Retrieves the name of the most recent intent matched to a dialog starter.

function getIntent(){return botContext.getDialogStarterIntent();}
Getting and setting variables

setBotVar: Sets a value to a session scoped bot variable.

function setBotVar(arg,val){botContext.setBotVariable(arg, val, true, false);}

getBotVar: Retrieves the value of a bot variable.

function getBotVar(arg){return botContext.getBotVariable(arg);}

getWebVar: Retrieves the value of a Web View variable.

function getWebVar(arg){return botContext.getWebViewVariable(arg);}

getEnvVar: Retrieves the value of an environment variable.

function getEnvVar(arg){return botContext.getEnvVariable(arg);}

setContextConv: Creates or updates a conversation-scoped variable and value in the Conversation Context Service for the default namespace defined in ‘__initConversation’.

function setContextConv(key, value) {
 var success = botContext.setContextDataForConversation(getBotVar('contextNameSpace'), key, value);
 if (success) {
   debugMsg("SETTING Context Data: Key: "+key+ "; Value: "+value);
 }else{
   debugMsg("FAILED to Set Context Data: Key: "+key+ "; Value: "+value);
 }
}

getContextConv: Retrieves a conversation-scoped variable’s value from the Conversation Context Service for the default namespace defined in ‘__initConversation’.

function getContextConv(key) {
 var success = botContext.getContextDataForConversation(getBotVar('contextNameSpace'), key);
 if (success) {
   debugMsg("GETTING Context Data: Key: "+key+ "; Value: "+success);
   return success;
 }else{
   debugMsg("FAILED to Get Context Data: Key: "+key);
 }
}
Debugging

debugMsg: Prints a debug message to the bot logs.

function debugMsg(arg){botContext.printDebugMessage(arg);}

debugVar: Prints a bot variable name and its value to the bot logs.

function debugVar(arg){botContext.printDebugMessage(arg + ': ' + getBotVar(arg));}

printVar: Sends a message to the user containing a bot variable name and its value.

function printVar(arg){botContext.sendMessage(arg + ": " + getBotVar(arg));}
Send messages

sendMsg: Sends a single text message to the user.

function sendMsg(arg){botContext.sendMessage(arg);}

sendMsgArr: Accepts an array of strings and sends each as a separate message to the user.

function sendMsgArr(arr){botContext.sendMessages(arr);}
Custom event logging

logEvent: Logs a simple custom event containing just the event name argument.

function logEvent(event_name) {botContext.logCustomEvent('', event_name, '');}

logEventAdv: Logs a full custom event containing arguments for user message, event name, and event details.

function logEventAdv(user_message, event_name, event_details){
  botContext.logCustomEvent(user_message, event_name, event_details);
}
Manage conversation flow

goNext: Navigates to a specific interaction.

function goNext(arg){botContext.setTriggerNextMessage(arg);} 

setDelay: Use in pre-process code to set a delay to the interaction in milliseconds.

function setDelay(arg){botContext.setMessageDelay(arg);}

goDefault: Configure to send a conversation to a bot’s default interaction (ex: Main Menu). Replace “platform.default” with that interaction's name.

function goDefault(){goNext("platform.default");}

trail: Sets a ‘breadcrumb’ variable containing the name of the current interaction. The interaction name is added to an interactionArray of previous ‘breadcrumb’ interactions, which can be used in ‘previous()’ function to enable ‘back’ functionality. Should be used with ALL question interactions.

function trail(val) {
 var e = getBotVar('intArr');
 if (e == 'null' || e == null || e.length === 0) {
   e = [];
 } else {
   e = e.split(',');
 }
 e.push(val);
 setBotVar('intArr', e.toString());
 var count = Number(getBotVar('errorCounter'));
 var breadcrumb = getBotVar('breadcrumb');
 if (breadcrumb != val) {
   count = 0;
 }
 setBotVar('errorCounter', count);
 setBotVar('breadcrumb', val);
}

previous: Used in conjunction with the ‘trail()’ function. ‘Pops’ interactions from the interactionArray and navigates to the most recent interaction. Typically used in its own dialog triggered by a ‘back’ pattern.

function previous(){
 var e = getBotVar('intArr').split(",");
 if(e.length === 1){
   debugMsg('You are already back to the start');
 }
 e.pop(); 
 setBotVar('intArr', e);
 goNext(e.pop());
}

Init variables

Automatically establishes frequently used values as bot variables. Includes LP Engagement Attributes as well as channel, account, user, and conversation-specific values. Is also used to establish default skills and registration of Conversation Context Service namespace.

 var initVars = {
   defaultSkillId: "",
   defaultSkillName: "",
   firstInteraction: 'WELCOME',
   transferMessage: 'Stand by!, transferring...',
   contextNameSpace: 'testNamespace',
   errorThreshold: 2,
   errorCount: 0,
   currentSkill: botContext.getLPEngagementAttribute("currentSkillId"),
   previousSkill: botContext.getLPEngagementAttribute("previousSkillId"),
   campaignId: botContext.getLPEngagementAttribute('campaignId'),
   accountId: botContext.getLPAccountId(),
   rtSessionId: botContext.getLPEngagementAttribute("rtSessionId"),
   sharkSessionId: botContext.getLPEngagementAttribute("sharkSessionId"),
   sharkVisitorId: botContext.getLPEngagementAttribute("sharkVisitorId"),
   bearerToken: botContext.getLPEngagementAttribute("BearerToken"),
   chatSessionKey: botContext.getLPEngagementAttribute("chatSessionKey"),
   agentSessionId: botContext.getLPEngagementAttribute("agentSessionId"),
   engid: botContext.getLPEngagementAttribute("engagementId"),
   conversationId: botContext.getConversationId(),
   customerInfo: botContext.getLPCustomerInfo(),
   userId: botContext.getUserPlatformId(),
   channel: botContext.getUserChannel(),
   customerId: botContext.getLPCustomerInfo().customerId,
   botId: "get from settings"
 };
 for(var i in Object.keys(initVars)) {
   setBotVar(Object.keys(initVars)[i], initVars[Object.keys(initVars)[i]]); // set each of the initVars as a variable
   debugMsg(Object.keys(initVars)[i]+ ": " +initVars[Object.keys(initVars)[i]]); // print a debug message for each of the variables set
 }
 botContext.registerContextNamespace(getBotVar('contextNameSpace'));

Many of these bot variables don't return information if you're testing from within Conversation Builder. It is recommended that you deploy your bot to a messaging test page.

Dialog templates

This bot template contains a dialog template that can be imported into any Conversation Builder bot.

If you import the dialog template into a bot, do so before you begin building out the bot. If you have existing global functions, there could be naming conflicts; so please double check after import.

Global Helper Functions

Contains all global helper functions and variables without the demonstration dialogs.

Included dialogs:

  • 00 - Global Functions README