Use the following built-in functions to affect the flow of a conversation.

Transfer to bot’s dialog

Contact your LivePerson representative to enable support for this scripting function.

Use transferToBotDialog to transfer the conversation to a specific dialog in a different Conversation Builder bot. This method gives you precise control over bot-to-bot transfers within LivePerson Conversational Cloud. It means more granular routing and a smoother hand-off experience for the consumer.

Function Name Arguments Returns
transferToBotDialog(botId, dialogName, transferMessage) botId (string) - The unique identifier of the target bot. You can find a bot’s ID in Bot Settings.

dialogName (string) - The name of the dialog in the target bot where the conversation should continue. You can find a dialog’s name in Dialog Settings.

transferMessage (string) - Specify the message to send to the consumer before the transfer happens. Or, specify an empty string or leave null if no message is needed.
None

Implementation approaches

  • Post-processing transfers: Use this function in the post-process code in a particular interaction to automatically transfer the consumer to a specific dialog in another bot after the interaction is complete. For example, if a user finishes an FAQ flow in one bot, you can seamlessly transfer them to a "feedback" dialog in a different bot.
  • Pre-processing transfers: In a text interaction that contains BLANK_MESSAGE, use the pre-process code to trigger this function. This allows you to perform the transfer before the interaction is even handled, enabling immediate and targeted routing.

Example

botContext.transferToBotDialog(e5522243-ba22-439e-b253-e5e8b123999f, Upgrade Plan, One sec. Were transferring you to an agent who can help.);

Set message delay value

Use setMessageDelay to set a delay for a message, so the conversation appears more human-like. As a best practice, use the function within the Pre-Process code of interaction. Note the following:

  • If you use this function in the Pre-Process code, it overrides the value that’s set in the Interaction Delay setting in the interaction.
  • If you use this function multiple times within your code, only the last instance is applied. In the code below, both Message1 and Message2 have a 5-second delay. Message1 doesn’t have a 3-second delay.
      botContext.setMessageDelay(3000);
      botContext.sendMessage(“Message1”);
      botContext.setMessageDelay(5000);
      botContext.sendMessage(“Message2”);
Function Name Arguments Returns
setMessageDelay(delay_value) delay_value (integer) None

Example

In the below example, we send three messages to the user with a delay of 2000 milliseconds between them.

// setting a delay of 2000 for each message……
botContext.setMessageDelay(2000);
//  sending message to user…
botContext.sendMessages(['Sorry to hear that you lost your credit card.','I just put the stop on your credit card', 'If you find any unauthorized transaction please let us know as soon as possible so we can remove them from your bill']);

Set allow max text response

By default, a single text interaction has a limit of 1000 characters on the word boundary before it gets split into 2 parts. However, you can override this behavior with the setAllowMaxTextResponse function so that all text is within a single message.

To accomplish this, use this function in the pre-process code of the interaction (i.e., before the interaction is rendered). You can then revert it if desired in a subsequent interaction.

Keep in mind the limits of the targeted channel(s), which might take precedence over this setting.

Function Name Arguments Returns
setAllowMaxTextResponse(value) value (Boolean) None
botContext.setAllowMaxTextResponse(true);

Set trigger next message

setTriggerNextMessage is used for directing the conversation flow, i.e., for triggering a specified interaction in the bot.

Function Name Arguments Returns
setTriggerNextMessage(messagename) messagename (string) — The name of the interaction to trigger. (An interaction's name can be found in the interaction's settings.) None

Don’t use the setTriggerNextMessage function within the __initConversation function within Global Functions. __initConversation is used to initialize the conversation context before anything happens. Using setTriggerNextMessage within __initConversation doesn’t work because the context isn’t fully initialized until __initConversation has been fully executed.

Example

In the example below, we test for which company the user selected, and, if "LivePerson", we trigger the interaction "Welcome LivePerson". Otherwise, we trigger "Welcome Other".

var company = botContext.getCurrentUserMessage();
if (company == 'LivePerson') {
      botContext.setTriggerNextMessage('Welcome LivePerson');
}else{
      botContext.setTriggerNextMessage('Welcome Other');
}

Evaluate options

evaluateOptions is used for matching the user’s input against an array of options.

Function Name Arguments Returns
evaluateOptions(userResponse, options) userResponse — the user's message text

options — array of strings
string: matched option from an array of options.

Example

In the below example, we create an array of possible options. Then we test for a response using the evaluateOptions() function by including the userResponse and the array of options. If the user types “A” or “A)” or “Yes” the result returned will be “A) Yes”.

var userResponse = (botContext.getCurrentUserMessage()).toLowerCase();
// match options
var options = ["A)Yes", "B)No"];
var result = botContext.evaluateOptions(userResponse, options);
// what was user's response?
botContext.printDebugMessage('====> User Said: ' + userResponse + ' and MATCH result = '+ result);

Add quick replies

The addQuickReplies function is used for adding quick replies to a message in JavaScript rather than defining in bot creation. This allows for the dynamic addition of the buttons to accommodate various scenarios.

Function Name Arguments Returns
addQuickReplies() array None

Example

The example below shows how quick replies can be added easily to your message.

// Add these quick replies to an existing message
botContext.addQuickReplies(['Ranch~sauce01','Honey Mustard~sauce02','BBQ~sauce03','Hot~sauce04']);

Get button payload

getButtonPayload is used to retrieve a button’s callback value that is sent to the bot when the consumer selects that button in a question.

By default, when you specify a callback value for a button in a Structured or Button question, that value is sent to the bot when the consumer selects the button. What’s more, that value, not the button’s label, is displayed to the consumer as their selected choice. The latter means you can retrieve the button’s callback value with getCurrentUserMessage.

However, in cases where you’re using the enableButtonTextOnPostback custom configuration field in the bot’s agent connector, the button’s label instead, not the callback value, is displayed to the consumer as their selected choice. In these cases, you need a different way to retrieve the button’s callback value. getButtonPayload meets this need.

Function Name Arguments Returns
getButtonPayload() None (string) The button’s callback value that is sent to the bot

Example

In this example, we use getButtonPayload in the Process User Response code of the question interaction to retrieve and store the callback value that is sent to the bot after the consumer selects a button:

var callbackValue = botContext.getButtonPayload();
botContext.printDebugMessage("Callback : " + callbackValue);
botContext.setBotVariable("callback", callbackValue, true, false);