Chat Widget¶

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

Installation¶

When you want to enable the DialoX chat widget on your own site, you need to add a bit of Javascript to your website. Just above the closing </body> tag, place the following script code:

<script>
  (function () {
    var el = document.createElement("script");
    el.setAttribute("src", "https://bsqd.me/js/widget.js");
    var config = {
      botId: "f294fb9a-2011-4dc4-8063-51c749d80467",
    };
    el.setAttribute("data-botsquad", JSON.stringify(config));
    document.body.appendChild(el);
  })();
</script>

where the value of botId needs to be replaced with the id of your bot. You will also find this script tag in the Connect section of the bot settings in the studio.

The following settings can be passed in to the chat widget's configuration.

botId: The bot UUID. This is the only required value.
locale: The language the widget is shown in. Must be one of the locales the bot is configured with; defaults to the detected browser locale.
timezone: Overrides the timezone for the user. Defaults to the browser's time zone.
userAgent: Override the browser user agent string
hostname: Override the hostname of the DialoX platform. Defaults to bsqd.me
secure: Whether to use HTTPS or not; defaults to true.
userId: Override the user ID for talking to the bot, for instance to be able to link it to a logged in user.
isPreview: Whether or not to use the non-published version of the bot; default false
context: A JSON object of values to add to the chat context for setting extra variables in the chat. Defaults to {}.

Most settings that deal with the layout and design of the widget are only configurable from the studio and cannot be specified from Javascript.

Configuration values that should be left alone:

userToken
frontend
socket_params

Adjusting the layout¶

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

primary color
widget button image
whatsapp button setting
call us button setting
contact form setting

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.

home:
  image_url: "https://mybot.com/avatar.png"
  title: "Hello 👋"
  description: "Welcome to MyBot!"
  conversation_cta: "Talk to us"
  team_message: "We are ready for your questions"
powered_by:
  text: "Powered by MyBot"
  url: "https://mybot.com/"

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:

chat_config:
  disabled_inputs:
    - 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 div.chat-messages {
    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.

ui:
  # 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:

ui:
  text_input_placeholder:
    $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.

Nudges¶

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:

Scripting¶

The widget exposes several Javascript functions which can be used to control it programmatically. Read more about the chat widget API.