Botsquad documentation logo

The BotSquad web SDK allows you to integrate your bot into your own website. Standard, every bot already has its own landing page, on https://bsqd.me/bot/<id>. Using the design tab in the studio, you can easily configure this landing page.

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).

When you want to go further, integrating the bot into your own website, please look at the Installation instructions.

The SDK has a demonstration page: visit sdk.botsqd.com to see the Javascript SDK in action.

Styling

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 BotSquad 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')
})

Standard emits

There are a few standard emit commands configured which modify the user interface. You do not need to write any Javascript code to use these events.

Standard events

The web client sends some predefined events to the bot script when some things happen in the client. These are the following:

These events can be used to track user behaviour (e.g. keeping track of which links are clicked); or waiting with the continuation of the bot’s script until the user has closed a modal:

say "Here is where I live:"
show location [lat: 52.364909, lon: 4.893414]
emit "trigger_modal" # to show the modal location popup
await event("$modal_close") # wait until the user dismisses the modal
say "Let's continue!"

Embedded mode

In embedded mode, 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.

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.

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

Installation

When you want to use the BotSquad bot on your own site, either embedded in the website or as an intercom-style chat widget, you need 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
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
hide_header [true/false], hide the header false
height Initial height of the box 400px
width Max width of the box 300px
layout [embedded, docked, minimized, hidden] docked
container_id Identifier of the container (when layout = embedded) N/A
socket The URL of the Botsquad websocket server. wss://botsqd.com/socket

Layout

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)

Multiple bots on one page

It is possible to have multiple bots on the same page. The SDK exposes the BotSquadHost class which can be used to instantiate a bot, as an alternative to using the data-botsquad= tag in the SDK script tag.

This way, you can have multiple bots instantiated. Take care that no 2 bots use the docked layout mode, otherwise they get in each other’s way. Use embedded or contained instead:

var bot1 = new BotSquadHost({"id":"d7200742-81ab-4bd9-a8e8-230a7fb7fe81","mode":"embedded","container_id":"container1"})
var bot2 = BotSquadHost({"id":"xxxxxxx2-81ab-4bd9-a8e8-230a7fb7fe81","mode":"embedded","container_id":"container2"})

bot1.message("talking to bot 1")
bot2.message("talking to bot 2!")

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