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

Widget-specific emits

Closing the current conversation and returning to the home screen of the web widget:

emit "close_conversation"

PWA-specific emits

Close the intro conversation and show the start screen:

emit "pwa_intro_done"

Return to the start screen from the ongoing conversation:

emit "pwa_menu"

Navigate to a specific URL or path:

emit "pwa_navigate", "http://example.com"

Standard events

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

$connect

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 != user.page do
    user.page = event.payload.origin
    remember user.page
  end
end

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 "https://www.botsquad.com"
  end

  await event("$link_click")

  say "Awesome!"
end

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!"
end

Operator events

The $operator_join, $operator_leave and $operator_action events are sent to a chat process whenever an operator from the Botsquad studio takes over the ongoing conversation. You can implement these events to create custom behaviour whenever that happens.

These three events are by default implemented in each bot, to ensure that any chat session can be taken over. The default implementation is the following:

dialog event: "$operator_join" do
  conversation.operator = event.payload
  say "#{conversation.operator.first_name} has joined the chat.", class: "system", typing_indicator: 0
  remember conversation
end

dialog event: "$operator_leave" do
  say "#{event.payload.first_name} has left.", class: "system", typing_indicator: 0
  conversation.operator = nil
  remember conversation
end

dialog event: "$operator_action" do
  action = event.payload
  if action.type == "message" do
    say action.payload, as: action.operator, typing_indicator: 0
  end
end