Botsquad documentation logo

The show statement is the generic statement which is designed to show a variety of media and user interface elements to the user.

Image

To show an image to the user, pass the image URL to show:

show image "https://studio.botsqd.com/images/botsquad-logo.png"

Embedded web page

To embed a web page in an iframe, use the web() function:

show web("https://www.youtube.com/embed/pwmEywQ1QUY")

By default the iframe’s size is 16 by 9, which is the standard movie aspect ratio for video. On click, the same iframe opens in a modal window.

You can also add classes to control the size and behaviour:

show web("https://www.youtube.com/embed/pwmEywQ1QUY"), class: "no-modal"

The following class names are supported:

Geographical location

Presents a small image of a map to the user, fixed at a certain geo location. Clicking it will open Google Maps.

location

Which is scripted like this:

say "This is where we are located:"
show location [lat: 52.364909, lon: 4.893414]

locations have two extra arguments which control the display of the map image: zoom and maptype:

show location [lat: 52.364909, lon: 4.893414], zoom: 18, maptype: "satellite"

location with display options

zoom is a number between 1 and 20, the default being 12. maptype is one of terrain, hybrid, satellite or roadmap (which is the default).

Buttons

The buttons element is modelled after Facebook’s Button Template, and supports all of its options. It is mostly used to create a menu, which is presented to let the user select between various options. It looks like this:

buttons template

Similar to quick replies you can show a button to the user giving one or more options.

  buttons "What do you want to do next?" do
    "Open CNN" ->
      open "http://cnn.com"
    "Say hello" ->
      event "say_hello", [message: "Hi"]
  end

Note that Buttons are different from quick_replies in that they don’t result in a user reply “text” you can match on in a dialog trigger; they are linked directly to actions. You can only use open and event inside button actions. So you cannot put a say directly inside a button; you would have to create a dialog with an event: trigger (see below).

Inside the buttons block, you can define a button to open a link by using open:

  open "http://cnn.com"

open is only used inside a button block. To show a ‘normal’ link to the user, just say the link, with a fully qualified URL: say "click here: http://cnn.com"

To trigger an event in the bot script when the user clicks a button, use event:

  event "say_hello"

You can also give an extra payload argument to event, which will be passed on in the event handler to contain a payload:

  event "say_hello", [message: "Hi"]

In the event handler, the event.payload variable is filled from the second, optional argument to event in the button declaration.

Handling button events

When in the above example, the button “Say hello” is clicked, the client posts back an event, with the name say_hello. To respond to this event you can create a dialog that catches this event, using event: matcher in the dialog declaration:

dialog event: "say_hello" do
  say "You clicked the 'Say Hello' button!"
  say "The message was: " + event.payload.message
end

Dynamic buttons

In the above example, the buttons were statically programmed in the bot script. This is fine for most situations, when you have a fixed menu to show, for instance. However it can be the case that you want to build up the list of buttons dynamically.

In that case, you use the buttons construction a bit differently, using the buttons builder function and passing it in the show statement:

dialog demo do
  # build the buttons
  button1 = [type: "web_url", title: "Open CNN", url: "http://cnn.com"]
  button2 = [type: "event", title: "Say hello", event: "say_hello", payload: [message: "Hi"]]
  # present them
  show buttons("What do you want to do next?", [button1, button2])
end

This example is identical to the first buttons example, but in this case, it is built up in runtime, so you can change the texts, the button order, et cetera, because everything is done using variables.

Button template limitations: The Facebook messenger API dictates that there must be at minium 1 button, and at most 3.

The gallery is modelled after Facebook’s Generic Template, and supports all of its options. It looks like this:

generic template

Which can be created using the template statement:

dialog demo do
 # show a gallery
 template do
  "Welcome to Jasper's market" ->
    subtitle "Fresh. Organic. Delicious."
    image_url "http://via.placeholder.com/350x150"
    default_action do
      type "web_url"
      open "http://facebook.com"
    end
    buttons do
    "Start shopping" ->
      event "start"
    "Call us" ->
      event "call"
    end
  end
end

In the above example, the gallery was statically programmed in the bot script. For galleries, however, you typically deal with variable data, e.g. when showing a number of items when you are creating a shopping bot.

In the case of dynamic data, you use the gallery template a bit differently, using the gallery_template builder function and passing it in the show statement:

dialog demo do
  # build the gallery data
  item = [
    title: "Welcome to Jasper's market",
    subtitle: "Fresh. Organic. Delicious.",
    image_url: "http://via.placeholder.com/350x150",
    default_action: [type: "web_url", url: "http://facebook.com"],
    buttons: [
      [type: "event", event: "start", title: "Start shopping"],
      [type: "event", event: "call", title: "Call us"]
    ]
  ]
  # present the gallery
  show gallery_template([item])
end

This example is identical to the first gallery example, but in this case, it is built up in runtime, so you can change the texts, the button order, et cetera, because everything is done using variables.

Gallery limitations: The Facebook messenger API dictates that there should be at minium 1 item, and at most 10 items. Gallery items can have up to 3 buttons each.

List template

The list template is modelled after Facebook’s List Template, and supports all of its options. It looks like this:

list template

Because lists are almost always constructed from dynamic data, it can only be modelled in a dynamic way, using the list_template function:

dialog list_demo do
  # build up the data
  item = [
    title: "Welcome to Jasper's market",
    subtitle: "Fresh. Organic. Delicious.",
    image_url: "http://via.placeholder.com/350x150",
    default_action: [type: "web_url", url: "http://facebook.com"]
  ]
  button = [type: "event", title: "Load more", event: "more"]
  # present the list
  show list_template([item, item, item], button)
end

The above example shows a list with 3 items (3 times the same item, in this case). A list template can have a single button on the bottom, which can be used for pagination or to let the user open a website.

List limitations: The Facebook messenger API dictates that there must be at minium 2 list items, and at most 4. Each list item can have only a single button.