Skip to content

JS Host

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…",
};