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");
Property | Description |
botDeploymentId (str) |
The |
webchatKey (str) | Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. |
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");
}
Property | Description |
action (str) |
What action to take on the BotXO Widget. Supported values are: |
webchatKey (str) | Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. |
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");
}
Property | Description |
module (str|arr) |
The module(s) that should trigger this method execution. Supported values are: - A single module ID, e.g. - A list of module IDs, e.g. - A wildcard character |
webchatKey (str) | Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. |
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");
}
Property | Description |
module (str) | The module ID the bot should go to. |
cvars (obj) | Optional. It is a plain object containing custom variables to be passed to the bot. |
webchatKey (str) | Unique Identifier for the Widget instance. You may have several Widget instances in your site and it is necessary to link this action to one of them. |
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);
}
Property | Description |
actionName (str | arr) |
The module(s) that should trigger this method execution. Supported values are: - A single module ID, e.g. - A list of module IDs, e.g. - A wildcard character |
webchatKey (str) | Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. |
* 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
});
Property | Description |
data (obj) | The information sent to the BotXO Widget. |
type (str) |
The action to be taken by the Widget. Supported values are |
message (str) | Required if type is set to message_bot . Property message refers to the text being printed by the bot. |
mod_id (int) | Required if type is set to "go_to_module" . Property mod_id refers to the module ID the bot should go to. |
cvars (obj) | Optional. It is a plain object containing custom variables to be passed to the bot. |
webchatKey (str) | Unique Identifier for the Widget instance. You may have several Widget instances in your site and it is necessary to link this action to one of them. |
openWebChat (bool) | Controls whether the BotXO Widget will stay open (or closed) after the action has been executed. |
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
Property | Description |
voiceEnabled (bool) | Shows the microphone option in the BotXO Widget. |
continuous (bool) |
Controls whether text-to-speech remains active when the visitor stops speaking ( If |
autoSend (bool) | Controls whether the bot will send the transcribed text immediately (true ) or it will wait for the visitor to send it (false ). |
timeToSend (int) | If this continuous and autoSend are set to true , this property controls the time (in seconds) the bot will wait for, between when the visitor stops speaking and the message is sent. |
language (str) | This property controls the language locale used by the both. It is related to speechEnabled. |
startAutomatically (bool) | Controls whether the bot will activate listening mode automatically each time it replies to the visitor. |
speechEnabled (bool) | (BETA) Activates the text-to-speech function of the bot, which is used to narrate the chat. If set to true , it uses the locale specified in language . |
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
Comments
0 comments
Please sign in to leave a comment.