Conversational Web SDK

This article covers the definition and examples of all the different functionalities provided by BotXO Conversational Web SDK. This JavaScript-based SDK allows you to design powerful interactions between the website and the widget. You can use the SDK in any environment that supports JavaScript.

BotXO Widget initialization

initBotXOChat() is responsible for initiating the BotXO Widget. It supports two arguments:

• BotXO configuration object (required)
• A callback function (optional)

Click here to see a list of supported properties for the BotXO configuration object.

initBotXOChat(
	{
		id: "0d7ba4fe-1345-4443-a004-c422f44f31c6",
	},
	callback //Function (optional)
);
    
function callback() {
  /*
    This function gets executed after the Widget is loaded and available in the DOM
  */
  console.log("callback");
}

BotXO Methods

getUuid

This method returns the unique BotXO visitor ID. This way, visitors behind log-in can be linked to specific visitor IDs. Visitors behind login can this way resume conversations independent of the device they are using. To resume a conversation, please refer to the property uId supported by the BotXO configuration object. 

botxo.getUid("botDeploymentId", "webchatKey"); 

widgetStatus

Allows to control the status of the Web Widget. Supported action properties are open, close, show, hide.

botxo.widgetStatus(
  {
    action: "open", // Required 
    webchatKey: "1", // Required if specified in initBotXOChat()
  },
  callback //Function (optional)
)

function callback() {
  /*
    This function gets executed after the action on the Widget
  */
  console.log("callback");
}

landedAt

Allows to perform arbitrary actions when the bot lands on a certain conversation module.

botxo.landedAt(
  {
    module: "43651", // Module ID as seen on the BotXO Canvas
    webchatKey: "1", // Required if specified in initBotXOChat()
  },
  callback //Function (required)
)

function callback() {
  /*
    This function gets executed after the bot has landed on the specified module ID
  */
  console.log("callback");
}

goTo

Allows to move the conversation to an arbitrary module ID and to pass custom variables to the bot

botxo.goTo(
  {
    module: "43651", // Required
    webchatKey: "1", // Required if specified in initBotXOChat()
    cvars: { // Pass custom variables to the bot (optional)
      key1: "value1",
      key2: "value2"
    }
  },
  callback //Function (optional)
)

function callback() {
  /*
    This function gets executed after the conversation has been pushed to the specified module ID
  */
  console.log("callback");
}

sendMessage

Allows to send a message on behalf of either the bot or the visitor.

On the bot-side, it supports sending: simple messages, messages with suggested replies, multiple messages, images.

On the visitor-side, only plain text messages are supported. 

Example

// Send a simple message on behalf of the bot
botxo.sendMessage(
  {
    sender: "bot", // Required
    message: "Hello! This is the bot", // Required
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

// Send a message on behalf of the bot with suggested reply options
botxo.sendMessage(
  {
    sender: "bot", // Required
    message: {
      text: "hello", // Required
      options: ["Bien", "Mal"], // Suggested reply options (optional)
    },
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

// Send an image on behalf of the bot
botxo.sendMessage(
  {
    sender: "bot", // Required
    message: { // Required
      type: "image",
      url: "https://s3.eu-central-1.amazonaws.com/botxo-assets-staging/media/cards/3541d1da-6e3.png",
    },
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

// Make the bot wait for some time
botxo.sendMessage(
  {
    sender: "bot", // Required
    message: {
      type: "wait",
      url: 2000,
    },
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

// Send multiple messages on behalf of the bot
botxo.sendMessage(
  {
    sender: "bot", // Required
    message: [
      {
        type: "text",
        url: "hello",
      },
      {
        type: "wait",
        url: 2000,
      },
      {
        type: "how are you?",
        url: "hello",
      },
    ],
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

// Send a simple message on behalf of the user
botxo.sendMessage(
  {
    sender: "user", // Required
    message: "Hello! This is the chat visitor", // Required
    webchatKey: "1", // Required if specified in initBotXOChat()
  }
)

getBotXOTransfer

Compared to botxo.landedAt(), this method allows to access custom variables* associated with the conversation. 

botxo.getBotXOTransfer({
  actionName: "*",
  webchatKey: "1",
  callback: (data) => callback(data) // The data object contains information such as the latest visitor message and custom variables
});

function callback(data) {
  /*
    This function gets executed after the conversation has arrived at the specified module ID
  */
  console.log(data);
}

* Important In order to access the custom variables associated with the bot, the following option needs to be enabled in the Bot Settings:

dataBotXOTransfer

Used to send custom variables together with actions to perform. 

botxo.dataBotXOTransfer({ 
  data: { 
    type: "message_bot", 
    message: "This is the content of the simulated message" 
  }, 
  webchatKey: "1", 
  openWebchat: true // Whether the chat should stay open after the message is sent 
}); 

Enable voice support

As of October 20th, 2020, the BotXO Widget supports voice control. BotXO Voice leverages the browser built-in text-to-speech* and speech-to-text** functionalities.

Supported properties

Example

// Initialize the BotXO Widget with voice support
initBotXOChat(
  {
    id: "615fc0de-c15c-4975-b517-78283d7f4bcd",
    webchatKey: "1", 
    voice: {
      voiceEnabled: 1, // Integer. By default, it is 0 (disabled).
      continuous: false, // boolean. By default, it is false (disabled).
      autoSend: 0, // Integer. By default, it is 0 (disabled).
      timeToSend: 1, //Integer
      language: "en-US", // String
      startAutomatically: 0, // Integer. By default, it is 0 (disabled).
      speechEnabled: 0, // Integer. By default, it is 0 (disabled).
    },
  },
  callback // Function (optional)
);

* To see the Browser compatibility for Text-To-Speech you can click here 

** To see the Browser compatibility for Speech-To-Text you can click here