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

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