Skip to content

Web-specific events

As Botsquad's web-based chat interfaces (the chat widget, the PWA and the host SDK) are the most rich environment for creating conversations, there are some events which have special meaning when they are emitted. These are documented below.

Standard emits

The emit commands below affect only the web chat interface. You do not need to write any Javascript code to use these events.

Hiding the input bar

emit "hide_input", true

Pass false to hide_input to show the input again.

Automatic modal pop-up

Automatically pop up the last chat message that has modal capabilities (currently images and iframes):

emit "trigger_modal"

And close the currently showing modal again:

emit "hide_modal"

Toast notification

Show a toast notification; a small message which disappears by itself after a few seconds:

emit "toast", message: "Item has been added to your favorites."

Standard events

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


This event is emitted whenever the user (re)connects to the chat, either as a new user or as a returning user. The event payload contains the origin URL.

Handle with care: The $connect event triggers very often, namely, every time the user reconnects with the chat, for whatever reason. So if you trigger a dialog every time on connect, the user keeps seeing the same dialog and might loose track of his original conversation. So the best practice is to catch this event in a task instead, for instance, to keep track of the page that the user is currently on:

task event: "$connect" do
  if event.payload.origin != do = event.payload.origin

This event is emitted whenever the user clicks any link in the chat window:

dialog link_click do
  buttons "Please click this link:" do
  "Botsquad website" ->
    open ""

  await event("$link_click")

  say "Awesome!"

This event is emitted when the user closes a modal popup (like a gallery, location, or image):

dialog show_place do
  say "Here is where I live:"
  show location [lat: 52.364909, lon: 4.893414]

  # to show the modal location popup
  emit "trigger_modal"

  # wait until the user dismisses the modal
  await event("$modal_close")

  say "Let's continue!"