Skip to content

Chat Widget

The chat widget presents a Botsquad bot as a regular chat widget on your website. Initially it shows as a small bubble, but when clicked a chat window pops out.

Script tag

In order to add the widget to your website, you need to add a script tag to your page. Usually you can create the script tag like this:

<script defer data-botsquad='{"id":"XXX"}' src=""></script>

Where you replace the XXX with your bot's ID (which can be found in the URL of the Botsquad Studio).

Dynamic script tag

In some environments, most notably in Google Tag Manager, it is not possible to set a data-attribute on a script tag, or the data attribute is stripped from the final tag. In this case, you can load the script dynamically with a small snipped of inline Javascript:

  (function() {
    var el = document.createElement('script');
    el.setAttribute('src', '');
    el.setAttribute('data-botsquad', '{"id":"XXX"}');


In the studio, the following aspects of the widget can be customized:

  • main color
  • widget button image
  • widget size
  • show conversations y/n

Widget customization using widget.yml

It is possible to add a YML file called widget to the bot. The properties from this file will be used to render the texts on the start screen of the widget, allowing deeper customization of the chat widget.

  image_url: ""
  title: "Hello 👋"
  description: "Welcome to MyBot!"
  conversation_cta: "Talk to us"
  team_message: "We are ready for your questions"
  text: "Powered by MyBot"
  url: ""

When configured like this, the home widget will look like the following:

The fields title, description, conversation_cta, team_message and powered_by.text can all be made translateable using the $i18n YAML syntax (see below)

Disabling certain input elements

It is possible to disable certain chat input elements by setting the chat_config portion of the widget YAML file:

  - location
  - image
  - text

Custom styling

It is possible to add extra CSS rules to the chat widget by adding an extra_css property in widget YAML file:

extra_css: |
  #botsquad-frame {
    background: red;

Since the widget runs in an iframe, this is the only way to add styles to the CSS widget. Using a normal stylesheet in the page that hosts the widget does not work.

Customizing the user interface labels

The chat user interface contains a few user interface labels that can be customized. These are for instance the text input placeholder label and several button labels.

By defining the labels YAML file, it is possible to customize these fixed labels.

  # Placeholder text for the main text input
  text_input_placeholder: "Type message…"
  # The label on the button for forms and item pickers
  form_submit_button: "Send"
  # Text for any cancel button
  cancel: "Cancel"
  # The label on the button for the location picker
  location_picker_select: "Select location"
  # widget: text of the button to start a new conversation
  new_conversation: "New conversation"
  # widget: caption text of the conversations list
  conversations: "All conversations"
  # widget: caption text of the conversations list link
  show_all: "Show all"

Any of these labels can be internationalized using the $i18n YAML syntax:

    $i18n: true
    en: "Type message…"
    nl: "Typ een bericht…"

These interface labels will adapt to the user's language, based on his web browser language and the language preference of his most recent conversation with the bot.


The chat widget is capable of triggering small "nudges" when the chat window is still closed. Nudges are small conversation starters: chat bubbles and UI elements that are triggered by conditions, like the visitor browsing to a certain web page:

Read more about nudges