Overview

Actions imply a change in the Chatbot. Any interaction between the user and the Chatbot is an action.

The actions are available inside the actions property of the chatbot instance.

chatbot.actions.displayChatbotMessage()

Important information

• []: Optional parameter.
• example1|example2: The parameter must have one of this values.
• example String: The parameter is String type.

Example

const messageData = {
  type:'answer',
  message:'Custom answer in conversationWindow',
}
chatbot.actions.displayChatbotMessage(messageData);

Available actions

Here is the list of all the actions available to you grouped by use:

Defining the Chatbot windows and their elements

• closeSideWindow
• disableInput
• enableInput
• displayChatbotActivity
• hideChatbotActivity
• hideCloseButton
• hideConversationWindow
• hideCustomConversationWindow
• hideUploadMediaButton
• setChatbotIcon
• setChatbotName
• showCloseButton
• showConversationWindow
• showCustomConversationWindow
• showSideWindow
• showUploadMediaButton
• updateConfiguration
• inbentaGetConfiguration

Manipulating the displayed Chatbot message

• displayChatbotMessage
• displaySystemMessage
• displayUserMessage
• updateMessage
• suggestAnswer

Handling user actions with the Chatbot

• sendMessage
• selectSystemMessageOption
• rateContent
• selectActionFieldOption
• uploadMedia
• downloadMedia

Interaction with the Chatbot state

• getConversationTranscript
• getSessionData
• setSessionData
• resetSession

Escalating to Benti

• escalateToAgent
• escalationStart
• createTicket

Others

• customTrigger
• setExternalInfo

closeSideWindow

This action closes the sideWindow if it is open.

chatbot.actions.closeSideWindow();

createTicket

This action creates a ticket in the Benti module. You must add an adapter subscribed to this action with onCreateTicket to create a ticket when this action is triggered.

The Inbenta "Create ticket" adapter is subscribed to this action in order to create a ticket in the Benti module. See the adapters page to understand how to use the Inbenta adapter.

chatbot.actions.createTicket(ticketData);

The ticketData parameter accepts the following parameters:

const ticketData = {
  FIRST_NAME: "John", // required
  LAST_NAME: "Doe", // optional
  EMAIL_ADDRESS: "jdoe@...", // required
  INQUIRY: "..." // required
}

From February 8th 2022, any other parameter that is added to the ticketData object is sent to the Benti API as ticket extra data using the externalSource name, when using the Inbenta Create Ticket adapter.

For example, in the following piece of code, COMPANY would be sent as ticket's extra data when creating the ticket.

const ticketData = {
  FIRST_NAME: "John", // required
  LAST_NAME: "Doe", // optional
  EMAIL_ADDRESS: "jdoe@...", // required
  INQUIRY: "..." // required,
  COMPANY: "Inbenta"
}

customTrigger

This action does not affect the behaviour of the SDK. It is only used in custom implementations to call the action and receive data through the subscription.

You can set up the customTrigger action as an intent callback, so it is called when the callback is executed. If you configured a subscription for this action, you can execute custom code without changing the behaviour of the SDK when the action is executed, either when a custom code calls the action, or when a callback is executed within an intent, with the current action configured as a function name.

chatbot.actions.customTrigger();

disableInput

This action disables input in the ConversationWindow.

chatbot.actions.disableInput();

displayChatbotActivity

This action displays a message at the bottom of the ConversationWindow with the message of your choice. This is to indicate, in external chats, that an external agent is writing.

activityData Object

• translate Boolean : translates the message in the given language(build configuration) if it matches a label.
• message String : Message to be displayed.

You can send an empty activityData to display a typing animation.

chatbot.actions.displayChatbotActivity(activityData);

displayChatbotMessage

This action displays a chatbotMessage with the information provided in the entry parameter. chatBotmessageData defines the type of message displayed.

const chatBotmessageData = {
  type:'answer',
  message:'Custom answer in conversationWindow',
}
chatbot.actions.displayChatbotMessage(chatBotmessageData);

chatBotmessageData Object

• type "answer"|"polarQuestion"|"multipleChoiceQuestion"|"extendedContentsAnswer"|"customAnswer": Type of Chatbot message. answer for normal answers, polarQuestion is for questions with yes/no options, extendedContentsAnswer is intended for federatedBot answers, and customAnswer skips the sanitizer.
• message String : Message to be displayed
• options options
• subAnswersanswer: Only used on extendedContentAnswer type.
• sideWindowContent [String]: Content inside the side-window
• sideWindowTitle [String]: Title for a side-window.
• trackingCode trackingCode
• media media
• custom custom
• obfuscate [Boolean]: If set to true, it obfuscates the next userMessage both in the input and in the Chatbot SDK history.
• suggestedAnswer[String]: Enters the given string in the chatbot input when the chatbotMessage is shown.
• parameters parameters
• actionField actionField
• actionFieldEvents actionFieldEvents
• groupedId [String] Identifier used to detect answers with multiple objects, use the same ID for this answers to allow the scroll to stop at the beginning of the first answer.
• stream [Boolean] When this parameter is set to true, chatbot replies will appear with a blinking cursor, as if the chatbot were streaming each message. This parameter also allows to display the blinking cursor with a blank message while the user waits for the chatbot's response to be returned. This value is only available if the answer type is type: answer.

options [array]: These are the displayed options that the user can select in the polarQuestion and multipleChoiceQuestion type. (For more information, see the sendMessage action). Each item in the options array has to be an object, with at least two keys: label and value:

• label String: Label shown when given multipleChoiceQuestion or polarQuestion
• value String|"yes"|"no": ID of the content displayed if the user clicks on the given option, "yes" or "no" in case of polarQuestion.
• revisitableLink String: Setting provided by the Chatbot API when the content has a directCall value. The setting is a hash string provided by the Chatbot API. This setting forces the SDK to keep links active and it is only provided when the options are multipleChoiceQuestion type.

trackingCode [object]: If rateCodeis set in chatBotmessageData and showRatingWithinMessages is set to "true" in the configuration, the rating widget is displayed within the Chatbot message. If showRatingWithinMessages is set to false (this is the default value), the rating widget is displayed in the side-window.

• clickCode String: Code sent to the API to track a match.
• rateCode String: Code sent to the API to track a rate.

media [object]: use this object to build a media message. When a user clicks the link, it triggers the onDownloadMedia subscription.

• name String: Name of the media file that is displayed.

custom [object]: Use this to store custom data in the message. It does not affect Chatbot functions.

parameters [object]: Used to set the related contents inside the answer, with the following structure:

• contents object: Configuration where the related contents are set up.
• contents.related object: This is where you set up relatedContents with all the needed information.
• contents.related.relatedTitle String: Label to use before showing the related contents.
• contents.related.relatedContents relatedContents

relatedContents [array]: This object contains both the title and the selector used by the SDK to ask for the relatedContent (either option or directCall).

• title String: Label shown as the title of the given relatedContent
• id String: The id given by the API, it must be a valid id given by the API. If the id setting is used, the relatedContent is disabled after the first click or if there is a new userQuestion.
• revisitableLink String: Setting provided by the Chatbot API when the content has a directCall value. The setting is a hash string provided by the Chatbot API. This setting forces the SDK to keep links active and accurately track user clicks. It is only provided when the options are multipleChoiceQuestion type.

• directCall String: If this setting is defined, it takes precedence over the id: when the user clicks on the relatedContent, it sends a directCall with the given value. This avoids disabling the relatedContent after the first click.

actionField [object]: This setting allows you to show either a dropdown or a button message. Intended to be used with variables of type List.

• fieldType [list|datePicker]: Use List (default value) to show buttons/dropdown, and datePicker when displaying the calendar.
• disableInput [Boolean]: When set to true, this disables the input, forcing the user to select a value from the button/dropdown.
• actionFieldId String: Parameter necessary to use as identifier to disable or change the method used on selection.
• actionMethod [sendMessage|addVariable]: By default, the sendMessage method applies if this setting is not defined internally. This action is the result of the user clicking on the dropdown/buttons, performing a sendMessage action or a addVariable action up on click.
• variableName String: Variable name from this field, the listValues parameter is the possible values of the variable.
• listValues Object listValues

listValues [object]: Possible values of the listed variable.

• displayType buttons|dropdown : Results in an answer with as many buttons as labels in the values parameter, or a dropdown with as many possible values.
• values [Array]: Array of objects with two parameters: Label to show in the button/dropdown, option to send internally either as option in the sendMessage action, or as addVariable value.

  values:
  [
    {"label":["Iphone 7"],"option":"Apple"},
    {"label":["OnePlus 6"],"option":"Android"},
  ]

actionFieldEvents [object]: Parameter used to disable and change the actionMethod of a given actionFieldId actionField.

• disable Array: Every actionFieldId inside the disable parameter automatically disables the given actionField.
• updateRequestedAction Array: Every actionFieldId inside the updateRequestedAction parameter automatically changes the actionMethod from sendMessage to addVariable.

Example

• Simple Answer:

const chatBotmessageData = {
  type:'answer',
  message:'Custom answer in conversationWindow',
}
chatbot.actions.displayChatbotMessage(chatBotmessageData);

• Simple Answer with side-window: Answer with a "more information" button. If the user clicks on the button, a side-window opens with its own title and content. When the user closes the side-window, the "more information" button displays again.

If the device has a width bigger than 768px, the sideWindow is displayed automatically.

const chatBotmessageData = {
  type:'answer',
  message:'Custom answer with more information in sideWindow',
  sideWindowTitle:"Test window title",
  sideWindowContent:"Test window Content"
}
chatbot.actions.displayChatbotMessage(chatBotmessageData);

• polarQuestion: Answer with two options in a button format. When the user clicks one of the buttons, the corresponding label is sent in the message and the value can be sent as an option in the sendMessage action.

const chatBotmessageData = {
    type: 'polarQuestion',
    message: 'Do you want to test a polarQuestion?',
    options: [
      {
        value: 'yes',
        label: 'yes'
      },
      {
        value: 'no',
        label: 'no'
      }
    ],
}
chatbot.actions.displayChatbotMessage(chatBotmessageData);

• multipleChoiceQuestion: Answer with multiple options. When the user clicks on an option, the corresponding label is sent in the message and the value can be sent as an option in the sendMessage action.

const chatBotmessageData={
        type: 'multipleChoiceQuestion',
        message: 'Which multipleContent do you wish to test?',
        options: [
          {
            value: 'TestContent1',
            label: 'TestContent1'
          },
          {
            value: 'TestContent2',
            label: 'TestContent2'
          },
          {
            value: 'TestContent3',
            label: 'TestContent3'
          }
        ],
      }
chatbot.actions.displayChatbotMessage(chatBotmessageData);

• extendedContentsAnswer: This type of answer has type: answer messages inside subAnswers array, similar to multipleChoiceQuestion type, but this allows to select different answers and the links are not disabled after every click. If a click trackingCode exists in each subAnswer, the click is automatically tracked.
• The messages inside subAnswers can trigger two different actions depending on the settings. Open a blank:_ page or redirect: SubAnswer must have a URL property.
  • url.value : Defines the url to be redirected.
  • url.target : [ _self| _blank ], if url.target is _self, it redirects the user when they click on the title. In other cases, it opens a new tab.
• OpenSideWindow: The subAnswer must have sideWindowTitle and sideWindowContent property and no URL property defined (you can trigger only one action after click, and redirect has priority)

  let SideWindowextended ={
    message: 'Introduction text for a km content',
    type: 'extendedContentsAnswer',
    subAnswers:[
      {
        attributes: {
          AnswerText: 'testAnswerText',
          SideBubble_text:'test SideBubble'
        },
        flags: [],
        message:'KMContent1Message',
        options:null,
        sideWindowTitle:"KM windowTitle content 1",
        sideWindowContent:"KM SideWindow content1!",
        parameters:{
          contents:{
            attributes:{
              SideBubble_text:'text'
            },
            title: 'example',
          }
        },
      },
      {
        attributes: {
          AnswerText: 'testAnswerText',
          SideBubble_text:'test SideBubble'
        },
        sideWindowTitle:"KM windowTitle content 2",
        sideWindowContent:"KM SideWindow content2!",
        flags: [],
        message:'KMContent2Message',
        options:null,
        parameters:{
          contents:{
            attributes:{
              SideBubble_text:'text'
            },
            title: 'example2',
          }
        },
      }
    ]
  }

• relatedContents: MessageData with relatedContents displayed using directCall setting(Need 1.13 or future verisons):

  var relatedMessage={
  message: 'Answer message with a side window',
  type: 'answer',
  parameters:{
    contents:{
      title:"example content title",
      related:{
        relatedContents:[{title: "Related content example", directCall: "<example>"}],
        relatedTitle:"You might also be interested in"
      }
    }
  }
  }
  chatbot.actions.displayChatbotMessage(relatedMessage);

• obfuscate: If the messageData has the obfuscate attribute set to true, it obfuscates the next userMessage both in the UI and in the Chatbot history.

var passwordMessage={
    message:"please enter a password, we will obfuscate it",
    obfuscate:true,
    type:'answer'
}
 chatbot.actions.displayChatbotMessage(passwordMessage);

• suggestedAnswer: If the messageData has the suggestedAnswer attribute, it displays the suggested message in the Chatbot input, with the same delay as the chatbotMessage.

  var suggestedAnswerMessage ={
      message:"Hey, how are you?",
      type:"answer",
      suggestedAnswer:"I'm not gonna small talk with a bot!!"
  }
 chatbot.actions.displayChatbotMessage(suggestedAnswerMessage);

• actionField: If the messageData has the actionField attribute and there is an existing listValues, it displays the possible values from the listValues attribute either as a dropdown or as buttons. If the fieldType is datePicker, it displays a date selector in the form of a calendar.

Dropdown Example:

  var dropdownList = {
    message: 'hello, what do you want to buy?',
    type:'answer',
    actionField: {
      disableInput: true,
      actionFieldId:'id1',
      actionMethod:'sendMessage',
      variableName:'super_hero',
      listValues: {
          displayType: "dropdown", // Possible values: 'buttons', 'dropdown'
          values:[
            {"label":["Iphone 7"],"option":"Apple"},
            {"label":["google pixel 3"],"option":"Google"},
            {"label":["Huawei P20 Pro"],"option":"Huawei"},
          ]
      }
    },
  };

DatePicker example:

 var datePicker = {
    message: 'message with datePicker!',
    type:'answer',
    actionField: { 
      fieldType:'datePicker', 
      disableInput: true,
      actionFieldId:'datePickeruuid',
      variableName:'date_purchase'
    }
  };

displaySystemMessage

This action creates a message in the conversationWindow with the system message format.

By default, the setting modal window is set to false. This means that if it is not specified, the systemMessage is displayed inside the conversationWindow (as shown in the first image).

When the systemMessage when the setting is modal: true, several things happen:

• The action displaySystemMessage does not return an id. You must add an id parameter to keep tracking the message.
• Input is temporarily disabled while the modal is active, and enabled back after the modal is closed.
• This message is not stored in the conversationTranscript.

const systemMessageData={
  translate: true,
  message: 'generic-error-message',
}
chatbot.actions.displaySystemMessage(systemMessageData);

SystemMessageData Object

• id [String]: Only used when modal is set to true, can be used to capture the selectedOption in a modal systemMessage.
• message String : Message to display.
• modal[Boolean]: Set to true to display the systemMessage as a modal (see the image below)
• options options
• replacements [Object : Replaces the variables of the message with the values in the replacements object. If the replacements object has a key with the name of a variable, this replaces the variable of the message with the value of the replacements key. The variables are defined as {variableName}. For example, {agentName} has joined is the message, {agentName} is a variable in the message. If you use a replacements object with a key agentName: "Mr Agent", the actual message becomes Mr Agent has joined.
• translate Boolean : Translates the message in the given language (build configuration) if it matches a label.
• maintainActive Boolean: if there are options in the message, it maintains those options enabled even after it has been clicked or is not the last message anymore
• custom custom

options array: These options display in the message as buttons that the user can select with a click. These buttons are only enabled when the message is the last in the conversation. Each item of the options array must be an object with at least one key: label:

• label String: Label shown inside the button.

Return

• return String: Returns unique id which identifies the message.

Example: (with modal: true)

modalSystemMessage = {
  message: 'Custom system Message with modal setting to true',
  translate: true,
  modal:true,
  id:"testingSystemMessage",
  options: [
     {label: 'First',value:'yes'},
     {label: 'Second', value:'no'}
  ]
}

displayUserMessage

This action creates a user message in the conversationWindow.

const userMessageData = {
    message: "Custom user message example",
}
chatbot.actions.displayUserMessage(userMessageData);

userMessageData Object

• custom custom
• media media
• message String : Message to be displayed.

Return

• return String: Returns unique id that identifies the message.

downloadMedia

This action carries the media object, with all the information required to download media on the user's device.

The action triggers when the user clicks a Chatbot or User message with a media property. It has the message's external id as a global property.

media Object

• messageExternalId String : The message external id of the message that the media belongs to.

chatbot.actions.downloadMedia({
  messageId: 'message-id-generated-when-displayed',
  messageExternalId: 'your-external-id',
  file: {
    name: 'file-of-agent.txt'
  }
});

enableInput

This action enables input in the ConversationWindow if it is disabled.

chatbot.actions.enableInput();

escalateToAgent

This action escalates to a chat with a human agent. You must add any adapter subscribed to this action (with onEscalateToAgent) that allows the chat conversation. One adapter that is subscribed to this action is the Inbenta Hyperchat adapter. Optionally, as with any other action or subscription, if a parameter is sent in the action, the subscription onEscalateToAgent receives the parameter.

chatbot.actions.escalateToAgent();

Example with parameter:

var escalationData = {
  name: "John",
  lastName: "Doe",
  inquiry: "I'm having problems logging in"
}
chatbot.actions.escalateToAgent(escalationData)

The subscription then receives this parameter, allowing the adapter to do whatever it needs with the information given.

escalationStart

You can use this action to send information between systems. The SDK never uses it by default, but some adapters may do so.

Do not confuse this action with the escalateToAgent action. If you are using Inbenta's Hyperchat with the NL Escalation Adapter 2:

• The NL Escalation Adapter 2 checks when the action escalationStart is called, in order to trigger the start of the escalation process. Calling this action therefore does not establish any connection with an agent, it just tells the escalation adapter to start the escalation process. This way, the adapter can check whether agents are available, or request any other information needed by the agents, like the user name.
• The Hyperchat Adapter checks when the escalateToAgent action is triggered and tries to establish a conversation with an agent. You can find more information on this in the NL Escalation Adapter 2 page.

chatbot.actions.escalationStart();

getConversationTranscript

This action returns an array with the last maxInteractions messages in the Chatbot conversation.

chatbot.actions.getConversationTranscript(conversationTranscriptData);

conversationTranscriptData Object

• maxInteractions number default:50 : Number of maximum interactions to return. If none is specified, maxInteractions = 50.

Return

This action can return a numeric index array of objects:

• agentIcon[String]: If user=assistant, displays the current agentIcon URL.
• agentName[String]: If user=assistant, displays the current agent name.
• clicked[boolean]: If user=assistant, tracks if the user clicked on any option.
• datetime String : dateTime the message was created.
• externalId String: external ID if it was previously set.
• id String: Unique id to identify the message.
• messageString : Message displayed.
• options [Array]: Options provided if type=PolarQuestion or MultipleChoiseQuestion.
• parameters[Object]: Contents that was displayed in the sideWindow.
• sideWindowContent[String]: Text displayed inside the sideWindow.
• sideWindowTitle[String]: Text displayed in sideWindow title.
• type "answer"|"polarQuestion"|"multipleChoiceQuestion": Type of answer.
• user: String assistant|guest: Who displayed the message.

getSessionData

This action retrieves all the information of the current conversation with the chatbot, messages, position of mainConversation and sideWindow, API sessionToken and expiration.

sessionData Object

• closeButtonVisibleobject: Visibility of the "close conversation button".
• messages messages Array: Array of messages.
• position Object: Current position of the conversationWindow.
• sessionToken String: Current sessionToken that the API uses to identify the session.
• sessionExpiration Number: sessionToken Expiration Date.
• SideWindowObject: Current state of the sideWindow component.
• sessionIdString: Session Identifier generated with the conversation.
• visible Boolean: Visibility of the conversationWindow.

var sessionData = chatbot.actions.getSessionData();

hideChatbotActivity

This action removes the ChatbotActivity if previously activated.

chatbot.actions.hideChatbotActivity(activityData);

hideCloseButton

This action hides the "close conversation" button.

chatbot.actions.hideCloseButton();

hideConversationWindow

This action closes the conversationWindow if it is open, and displays the launcher.

chatbot.actions.hideConversationWindow();

hideCustomConversationWindow

This action hides the customConversationWindow if it is open, and restores the original conversationWindow with the chatbot, user messages and input.

chatbot.actions.hideCustomConversationWindow();

hideUploadMediaButton

This action hides the "Upload media" button.

chatbot.actions.hideUploadMediaButton();

rateContent

This action is used by the ratigns up on clicking on a rate content.

trackingData

• trackingCode String : The trackingCode necessary to send to the API, gives context about wich content are we going to rate.
• value String : Value of the rating
• comment [String] Optional comment to send with the rating, is usually used on the negative rating.

const trackingData = {
  trackingCode: "<example>",
  value: "1",
}
chatbot.actions.rateContent(trackingData);

resetSession

This Action deletes the session data and restore it to the build value. This means that:

• The API client that the Chatbot instance uses deletes the session token. The next request to the Inbenta API creates a new session token.
• The message list is removed.
• The main window is hidden and the launcher displays. When the user opens the conversation window again, its position is the build configuration position (or the default position if unchanged). User input is enabled if it was disabled.
• The side window is hidden and its values are reset so it is empty.

chatbot.actions.resetSession();

selectActionFieldOption

This action is the result of selecting a value of a chatbot message with actionField parameter, either selecting a value in the dropdown or a button.

ActionFieldData Object

• method[sendMessage|addVariable]: This parameter what action to take with this data:
  • sendMessage: The label parameter displays as a userMessage, and there is a sendMessage action with message:label and userActivityOptions:value.
  • addVariable: The variableName parameter and value are used in the addVariable API method and a systemMessage displays with the label selected-option.
• variableName [String] This is only mandatory when selecting the addVariable method.
• value String: This is the value sent to the API either as the value in the addVariable endpoint, or as userActivityOptions in the messageData object in the sendMessage action
• label [String]: This displays as a userMessage when sendMessage method selected. It is also sent as a message in messageData object in the sendMessage action

AddVariable example:

chatbot.actions.selectActionFieldOption({
  method:"addVariable",
  value:"Huawei",
  variableName: "phoneBrand",
})

SendMessage example:

• We don't need to set up the method since sendMessage is the default one.

chatbot.actions.selectActionFieldOption({
  value:"Huawei",
  label: "Huawei p20 pro",
})

selectSystemMessageOption

This action carries the system message id and the option object of a system message. The Chatbot dispatches this action every time a user clicks on a System Message button.

optionData Object

• id String: The id of message of the selected option.
• option option

sendMessage

This action sends a message to the Inbenta API, and displays the answer as a chatbotMessage.

var messageData = {
    message: "Custom user message example",
}
chatbot.actions.sendMessage(messageData);

messageData Object

• message String : Message sent to Inbenta API.
• userActivityOptions [String]: Option selected when given options in previous message (polarQuestion|multipleChoiceQuestion)
• directCall[String]: directCall property takes priority over message and userActivityOptions, ignoring both parameters and only sending to the API the given directCall value. With this parameter, you can force Chatbot to retrieve a specific content, regardless of the previous context.

You must set up the required value in the Dynamic Setting called “DIRECT_CALL”. This can be any name you want (e.g. ESCALATE_FORM).

var directMessageData = {
    message: "",     
    directCall: "ESCALATE_FORM"
}
chatbot.actions.sendMessage(directMessageData);

As a result, upon matching the call, the Chatbot displays the content with the specified directCall value (ESCALATE_FORM).

If the content does not exist (e.g. if there is a typo in the Direct Call value), the Chatbot returns a generic error message with the ‘conversation-error-message’ flag. The Chatbot then resets itself to its initial state.

setChatbotIcon

This action changes the Chatbot icon in subsequent Chatbot messages.

const iconData = {
source: 'url',
url: 'https://www.inbenta.com/wp-content/themes/inbenta/img/icons/inbentabot.svg'}
chatbot.actions.setChatbotIcon(iconData);

iconData Object

• source "url|default" : Set it to "url" if you use an external URL, or default to use the default chatbotIcon.
• url [String]: Image URL. It must be a valid image URL, otherwise it returns an error.

setChatbotName

This action changes the Chatbot name in subsequent Chatbot messages.

const nameData = {
source: 'name',
name: 'Veronica from Inbenta'}
chatbot.actions.setChatbotName(nameData);

nameData Object

• source "name|default" : Set to 'name' to use a custom name, default to use default chatbotName.
• name [String]: Name to display.

setExternalInfo

This action can be used to send information between systems. The SDK never uses it by default, but some adapters may, e.g. the HyperChat external adapter.

chatbot.actions.setExternalInfo({data:'test'});

setSessionData

This action deletes the current state of the chatbot and overwrites it with the given configuration.

This is useful when you transfer the conversation from one domain to another. With the setSessionData action, the user can continue the conversation from a completely different website.

sessionData Object

• messages messages Array: Array of messages.
• position object: Current position of the conversationWindow.
• sessionToken String: current sessionToken that the API uses to identify the session.
• sessionExpiration Number: sessionToken Expiration Date.
• SideWindowobject: Current state of the sideWindow component.
• closeButtonVisibleobject: Visibility on close conversation button is visible.

chatbot.actions.setSessionData(sessionData);

showCloseButton

This action shows the "close conversation" button.

chatbot.actions.showCloseButton();

showConversationWindow

This action hides the launcher and shows the main ConversationWindow.

chatbot.actions.showConversationWindow();

showCustomConversationWindow

This action shows a custom element with the given HTML in the conversationWindow. The content is not saved: the HTML must be sent every time the action is called.

chatbot.actions.showCustomConversationWindow(customhtml);

customhtml Object

• content String: This is the HTML content of the customConversationWindow.
• showLoader Boolean: When set to true, the SDK shows a loader using the customConversationWindow.

Example: (with a simple form inside the customConversationWindow)

var customWindowHTML = {
  content: '<form>'
      +'First name:<br>'
      +'<input type="text" name="firstname" value="Luke">'
      +'<br>Last name:<br>'
      +'<input type="text" name="lastname" value="Skywalker"><br><br><input type="submit" value="Submit"></form> '
}

chatbot.actions.showCustomConversationWindow(customWindowHTML);

//Show loader:
chatbot.actions.showCustomConversationWindow({showLoader:true});

showSideWindow

This action creates a sideWindow with its own content and title. If a tracking code is attached, the ratings widget is shown too.

const SideWindow = {
  sideWindowContent: "<p>Example of a custom WindowContent</p>",
  sideWindowTitle: "Test title",
}
chatbot.actions.showSideWindow(SideWindow);

SideWindow Object

• sideWindowContent String : data shown inside the sideWindow, it accepts HTML tags.
• sideWindowTitle String : Title of the sideWindow
• trackingCode trackingCode

showUploadMediaButton

This action shows the upload-media button.

chatbot.actions.showUploadMediaButton();

suggestAnswer

This action shows a message in the chatbot input. This message can then be modified or sent by the user. The input message shows after the delay set in the configuration.

suggestAnswer Object

• message String: The message that shows in the chatbot input.

var suggestAnswerData={
    message:'Test input suggestion'

}
chatbot.actions.suggestAnswer(suggestAnswerData);

updateConfiguration

This action allows you to modify the configuration given in the build method. It gives new values to the following configurations:

NewConfiguration Object

• labels object: The new labels to override the original ones.
• launcherobject: The new configuration to set the launcher.title
• inputCharacterCounterboolean: Updates the configuration of the character counter.
• inputCharacterCounterMaxnumber: Updates the configuration of the maximum characters in the input box. The Chatbot allows a maximum value of 256 characters for this configuration, but this method can be used to set it to a maximum of 4096 characters, to allow users to send longer texts when the Chatbot SDK escalates to a live chat with an agent. When used with the Chatbot, the value should be set back to the maximum of 256 characters.

var newConfiguration={
    labels:{
        'interface-title':'Custom interface title'
    },
    launcher:{
        'title':"Custom launcher"
    },
    inputCharacterCounter: true,
    inputCharacterCounterMax: 100
}
chatbot.actions.updateConfiguration(newConfiguration);

updateMessage

This action modifies a message in the conversation.

There are different type of modifications:

• Add waiting icon. action:WAITING_TICK
• Add single tick icon. action:SINGLE_TICK
• Add double tick icon. action:DOUBLE_TICK
• Add error icon. action:ERROR_TICK
• Set an external ID. action:UPDATE_EXTERNAL
• Update a system message. action:UPDATE_SYSTEM_MESSAGE
• Update a chatbot message. action:UPDATE_CHATBOT_MESSAGE
• End streamed chatbot message. action:END_STREAMED_MESSAGE

You can select the message with the id given in the return value of the action displayUserMessage.

If the payload has an externalId, it takes priority over the id and selects messages by externalId.

const payload = {
   id: '751bcdf4-204d-4653-bf4c-21b2fe46202b',  // IMPORTANT: there must be a message in the conversation with this id
   action: 'SINGLE_TICK'
}
chatbot.actions.updateMessage(payload);

payload Object

• id [String] : the uuid of the message that should be updated. The updateMessage function fails if the id is not a string, or if there is no message with this id.
• action "SINGLE_TICK"|"DOUBLE_TICK"|"WAITING_TICK"|"ERROR_TICK"|"UPDATE_EXTERNAL": the update action to apply.
• externalId[String] : If given an externalId, it takes priority over the id when looking for the message to update.
• newExternalId[String] : If given the action "UPDATE_EXTERNAL", it sets the given message externalId for this newExternalId.
• messageData[Object]: Available only when action:UPDATE_CHATBOT_MESSAGE. This is the chatBotmessageData object used in the displayChatbotMessage action.

Updating a system message

When the action is UPDATE_SYSTEM_MESSAGE, the payload accepts the same parameters as the displaySystemMessage action. Remember that you must specify the uuid of the message that you want to update.

// payload example
const payload = {
   id: '751bcdf4-204d-4653-bf4c-21b2fe46202b',  // IMPORTANT: there must be a message in the conversation with this id
   action: 'UPDATE_SYSTEM_MESSAGE',
   translate: true,
   message: 'generic-error-message',
}
chatbot.actions.updateMessage(payload);

Example

uploadMedia

This action carries on the media object, with all the information to upload media from the user's device. It triggers when the user clicks the upload-media button and selects a file. Before this happens, a displayUserMessage with the media object is dispatched.

The uploadMedia action only triggers the onUploadMedia subscription. It does not do anything by itself. This means that you need an adapter to listen for the subscription and do something accordingly.

If you want to "force" the uploadMedia action to send an attachment to the HyperChat agent, the file data sent to the uploadMedia action must be a File object:

media Object This action carries all the necessary information to download a file, with the message id and the message external id that it is related to.

• messageId String : The message id of the message that the media belongs to.
• file Object : You need the name property of the file to display this name in the messages. You can add other properties if needed.
  • name String : The name of the file to display in the message.

chatbot.actions.uploadMedia({
  messageId: 'message-id-generated-when-displayed',
  file: new File(['foo', 'bar'], 'foobar.txt');
});

You must also specify the user message id in the uploadMedia action data:

let myFile = new File(['foo', 'bar'], 'foobar.txt');
      // Display the user message with the attachment file name
      let userFileMessageId = chatbot.actions.displayUserMessage({
        message: 'upload ' + myFile.name,
        media: myFile
      });
      // Execute the uploadMedia action
      chatbot.actions.uploadMedia({
        messageId: userFileMessageId,
        file: myFile
      });

inbentaGetConfiguration

This action allows you to get the current configuration. You can use it when the configuration has been updated with the updateConfiguration action and you want to get the current values.

configuration Object The method returns the same parameters that can be updated with the updateConfiguration action. It might add extra parameters, like the initial values for certain configurations.

• labels object: The current labels.
• launcherobject: The current launcher.title.
• inputCharacterCounterboolean: The current character counter configuration.
• inputCharacterCounterMaxnumber: The current maximum number of characters allowed in the input box.
• inputCharacterCounterMaxInitialValuenumber: The initial value of the maximum number of characters allowed in the input box, that was set when the SDK was loaded for the first time.

const configuration = chatbot.actions.inbentaGetConfiguration();