JS Host SDK

The DialoX host SDK allows you to deeply integrate your bot into your own website, where the chat window is nested in a container <div>.

The chat window initializes itself inside a container (given by the container_id configuration option). This way, it is really integrated with the rest of the website.

You can change how the bot looks using CSS (See the Styling section for that), and even how it behaves (see the "interacting with the bot" further down below).

Installation¶

When you want to embed the DialoX bot into your own site, you need to add a bit of Javascript to your site. Just above the closing </body> tag place the following tag:

<script
  data-botsquad='{"id":"1adc3f20-32e9-4376-a147-d9ef23ac8a4c"}'
  src="https://bsqd.me/js/host.js"
></script>

where id is the id of your bot. In the data-botsquad attribute, you can set more configuration variables, listed below.

Configuration¶

To get the bot up and running we need to know a couple of things. You can place these variables in the data-botsquad attribute of the JS include. Note that the id parameter is required, as it is the identifier for which bot to use.

Parameter	Description	Default
id	The id of the bot that you want to	Required value
container_id	Identifier of the container div	Required value
layout	[embedded, contained]	`embedded`
locale	The language that the bot will start speaking. Should be one of the configured languages the bot can speak.	Defaults to the browser language, if the bot supports it, otherwise the bots first language.
user_id	The id of the user that is talking to the bot.	When no user id is given, an ID will be generated and stored in a cookie
context	Arbitrary parameters to be set in the bot script	`{}`
css_variables	Override CSS variables in the style sheet. See the "styling" section below.	`{}`
hide_input	[true/false], hide the input box	`false`
socket	The URL of the DialoX websocket server.	wss://botsqd.com/socket
g	The group name, to create a separate conversation.	`main`

Layout¶

embedded - The container auto-adjusts its size to the container. The height of this container gets automatically adjusted to the height of the chat, so that the entire chat history always fits in the container.
contained - The chat container should have a fixed height, and will be scrollable. (overflow: auto).
hidden - not visible

Setting the viewport tag

For optimal responsiveness, add a <viewport> tag which prevents the browser from zooming in / out: <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />

CSS variables¶

The SDK uses CSS variables to style certain commonly used elements of the conversation UI. The following variables can be set:

Parameter	Description	Default value
`main_color`	The main highlight color	`#0084ff`
`secondary_color`	The secondary color	`rgba(0,0,0,0.1)`
`ui_color`	The color of general UI elements	`#bbbbbb`
`ui_background_color`	The background color of general UI elements	`rgba(255,255,255,0.9)`
`bubble_radius`	The radius of the chat bubbles	`20px`
`bot_avatar_size`	The display size of the bot avatar	`31px`
`user_avatar_size`	The display size of the user avatar	`15px`
`border_style`	The style of the borders	`1px solid #ddd`
`animation_delay`	The speed of the animation	`400ms`

Note that you can also set these variables using normal CSS syntax. All CSS variables are prefixed by --botsquad- and all underscores are replaced by dashes. So main_color becomes the variable --botsquad-main-color:

:root {
  --botsquad-main-color: orange;
}

For other styling suggestions, please look in the DialoX studio in the Design section, where you can find examples of stylesheets which you can use to style the chat widget.

Interacting with the bot¶

Message¶

Type back at the bot without using the input box.

BotSqd.message("Hi thanks for listening!");

Media¶

Send an image, video, audio or regular file URL.

BotSqd.media("image", "http://example.com/image.jpg");
BotSqd.media("video", "http://example.com/image.mp4");
BotSqd.media("audio", "http://example.com/image.wav");
BotSqd.media("file", "http://example.com/image.txt");

Location¶

Send a geographical coordinate to the chat

BotSqd.location(lat, lon);

Event¶

Trigger an event from your site to the bot.

This:

BotSqd.event("show_it");

Will trigger:

dialog event: "show_it" do
  say "Did you see it?"
end

Subscribing to bot events¶

Using BotSqd.on(), the hosting code can receive events that are related to the SDK integration.

BotSqd.on("closed", (data) => {
  console.log("Closed the bot");
});

The following events are available:

Name	When
`loaded`	The script has been loaded
`morphing`	The chat control has start changing it's appearance
`morphed`	The chat control has changed his appearance
`opening`	The embedded chat control is opening
`opened`	The embedded chat control has been opened
`closing`	The embedded chat control starts closing
`closed`	The embedded chat control has been closed

Subscribing to emit methods¶

Using emit, the bot can send named actions with a payload to the hosting client. These events can be caught in the client by using onEmit.

emit "set_background_color", [color: "black"]

You can subscribe to these events like this:

BotSqd.onEmit("set_background_color", (data) => {
  console.log(
    `We should write some content here to set our bg color to $(data.color)!`
  );
});

Retrieve the last emitted event¶

When the page is reloaded, the bot starts again, loading its chat history with the user. The client then might need to set its state accordingly, based on the events that have been emitted to the client in the past. Using getLastEmitted(), you can retrieve the given event from the bot's history and receive the payload.

BotSqd.getLastEmitted(
  "set_background_color",
  (data) => {
    // success callback, the data element will contain: {color: 'black'}
    console.log("success", data);
  },
  () => {
    // error callback, event not found
    console.log("no background color has been set in the bot yet");
  }
);

Change config using JavaScript¶

Most configuration values can be set in runtime. A few variables can only be set on initialization of the bot, these are id, user_id and context. All other variables can be dynamically changed, like in the example below:

// Getting a value (getting the visibility of the input box)
BotSqd.config("hide_input"); // = false

// Setting a value (hiding the input box)
BotSqd.config("hide_input", true); // = true (will return the new value of the configurable item)

Customizing / internationalizing the labels¶

Some parts of the web user interface have hardcoded labels; amongst others the location picker's confirm button, the form submit button and the text "Cancel" that is sent. You can override these by supplying a global BotSqd.labels dictionary, which contains alternative values for these:

BotSqd.labels = {
  location_picker_select: "Kies locatie",
  form_submit_button: "Opslaan",
  cancel: "Annuleren",
  text_input_placeholder: "Typ een bericht…",
};