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

Note: All examples shown are set in a Production environment.

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


Important information

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

This page explains all the actions available to you. They are listed in alphabetical order:


This action closes the sideWindow if it is open.



This action does not have any consequence on the SDK behaviour, it is only used so custom implementations can call the action and get the data through the subscription.



This action disables input in the ConversationWindow.



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.



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

const chatBotmessageData = {
  message:'Custom answer in conversationWindow',

chatBotmessageData Object

  • type "answer"|"polarQuestion"|"multipleChoiceQuestion"|"extendedContentsAnswer"|"customAnswer": Type of Chatbot message. answer for normal answers, polarQuestion is for questiosn with yes/no options, extendedContentsAnswer is intended for federatedBot answers, and customAnswer will skip 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, the next userMessage will be obfuscated, both in the input and in the Chatbot SDK history.
  • suggestedAnswer[String]: Will enter the given string in the chatbot input when the chatbotMessage is shown.
  • parameters parameters
  • actionField actionField
  • actionFieldEvents actionFieldEvents

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 that will be sent when the content has a directCall value, which will cause the SDK to not disable the links on which there is a defined revisitableLink.(multipleChoiceQuestion case)

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.
    Important: These codes must be identical to the codes that the API returns, otherwise an error occurs when it sends the request to the Inbenta API.

media object: use this object to build a media message, up on clicking the link, it will trigger the onDownloadMedia subscription.

  • name String: Name of the media file that will be 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: relatedContents will be set up here, with all the needed information.
  • contents.related.relatedTitle String: Label that will be used before showing the related contents.
  • contents.related.relatedContents relatedContents

relatedContents array: This object will contain 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.
  • directCall(deprecated) 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.
  • revisitableLink String: Setting exactly the same as directCall, but allows the API to properly do the tracking on user clicks.

actionField object: This setting will allow the display of either a dropdown or a button message. Intended to be used with variables of type List.

  • fieldType [list|datePicker]: List(default value) will be used for displaying buttons/dropdown, and datePicker when displaying the calendar.
  • disableInput [Boolean]: When set to true, will disable 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, if this setting is not defined, internally we will apply the sendMessage method. This is the action resulting on the user clicking on the dropdown/buttons, performing a sendMessage action or a addVariabel 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 : Will result 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 2 parameters: Label will be displayed in the button/dropdown, option will be internally send either as option in the sendMessage action, or as addVariable value.
    {"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 will automatically disable the given actionField.
  • updateRequestedAction Array: Every actionFieldId inside the updateRequestedAction parameter will automatically change the actionMethod from sendMessage to addVariable.


  • Simple Answer:
const chatBotmessageData = {
  message:'Custom answer in conversationWindow',


  • 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 = {
  message:'Custom answer with more information in sideWindow',
  sideWindowTitle:"Test window title",
  sideWindowContent:"Test window Content"

custom_answer custom_answer

  • 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'


  • 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'


  • 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.
    • : [ _self| _blank ], if is _self, the user will be redirected on click in the title, in any other cases, it will open 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',
        attributes: {
          AnswerText: 'testAnswerText',
          SideBubble_text:'test SideBubble'
        flags: [],
        sideWindowTitle:"KM windowTitle content 1",
        sideWindowContent:"KM SideWindow content1!",
            title: 'example',
        attributes: {
          AnswerText: 'testAnswerText',
          SideBubble_text:'test SideBubble'
        sideWindowTitle:"KM windowTitle content 2",
        sideWindowContent:"KM SideWindow content2!",
        flags: [],
            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',
        title:"example content title",
          relatedContents:[{title: "Related content example", directCall: "<example>"}],
          relatedTitle:"You might also be interested in"


  • 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 obpfuscate it",


  • 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?",
      suggestedAnswer:"I'm not gonna small talk with a bot!!"


  • 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?',
    actionField: {
      disableInput: true,
      listValues: {
          displayType: "dropdown", // Possible values: 'buttons', 'dropdown'
            {"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!',
    actionField: { 
      disableInput: true,



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',

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, the variable of the message will be replaced 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 message will be Mr Agent has joined.
  • translate Boolean : Translates the message in the given language (build configuration) if it matches a label.
  • 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.

Note: If the bot is configured with both systemMessage.modal=true and'exitConversation', it triggers the resetSession action upon user confirmation, as they had clicked on the closeConversation button.


  • 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,
  options: [
     {label: 'First',value:'yes'},
     {label: 'Second', value:'no'}



This action creates a user message in the conversationWindow.

const userMessageData = {
    message: "Custom user message example",

userMessageData Object

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


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



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.
  messageId: 'message-id-generated-when-displayed',
  messageExternalId: 'your-external-id',
  file: {
    name: 'file-of-agent.txt'


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



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.


Example with parameter:

var escalationData = {
  name: "John",
  lastName: "Doe",
  inquiry: "I'm having problems logging in"

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


This action can be used to send information between systems. The SDK never uses it by default, but some adapters may do it.



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


conversationTranscriptData Object

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


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.


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


This action removes the ChatbotActivity if previously activated.



This action hides the "close conversation" button.



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



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



This action hides the "Upload media" button.



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


  • 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",


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.

Important: To reset the Chatbot session, removing cookies does not work. Instead, you must call the resetSession action. When you develop with the Inbenta Chatbot SDK, you can either set an HTML click-eventlistener button to execute the resetSession action, or use the default "Close" button. When you use the Inbenta Chatbot SDK in production, you may allow users to reset the session when they activate the "Close" button, or customise the behaviour of another element to trigger the resetSession action.



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:

  variableName: "phoneBrand",

SendMessage example:

  • We don't need to set up the method since sendMessage is the default one.
    label: "Huawei p20 pro",


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


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

var messageData = {
    message: "Custom user message example",

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"

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.


This action changes the Chatbot icon in subsequent Chatbot messages.

const iconData = {
source: 'url',
url: ''}

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.


This action changes the Chatbot name in subsequent Chatbot messages.

const nameData = {
source: 'name',
name: 'Veronica from Inbenta'}

nameData Object

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



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.



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.


This action shows the "close conversation" button.



This action hides the launcher and shows the main ConversationWindow.



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.


customhtml Object

  • content String: HTML that will be printed inside 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> '


//Show loader:



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",

SideWindow Object

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



This action shows the upload-media button.



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

suggestAnswer Object

  • message String: The message that will be shown in the chatbot input.
var suggestAnswerData={
    message:'Test input suggestion'




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
var newConfiguration={
        'interface-title':'Custom interface title'
        'title':"Custom launcher"




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

The message can be selected using the id given in the return value of the action displayUserMessage.

If the payload has an externalId, it will take priority over the id for selecting the message 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'

payload Object

  • id [String] : the uuid of the message to which the update must be applied. 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 we want 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", will set the given message externalId for this newExternalId.




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.

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.
  messageId: 'message-id-generated-when-displayed',
  file: {
    name: 'file-of-user.txt'