Skip to content

UI elements

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.combotsquad-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 CSS classes to control the size and behaviour:

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

The following built in CSS class names are supported:

  • full - take the full width of the chat window instead of 80%
  • no-modal - do not trigger a modal window when clicking the frame
  • square - Square frame size
  • four-by-three - Size the frame to 4:3 aspect ratio
  • three-by-two - Size the frame to 3:2 aspect ratio
  • two-by-one - Size the frame to 2:1 aspect ratio
  • two-by-three - Size the frame to 2:3 aspect ratio (portrait)
  • three-by-four - Size the frame to 3:4 aspect ratio (portrait)
  • fullscreen - Show the modal screen full screen

Combining class names also works, e.g. when you want to show a portrait image in the chat stream, but full screen when clicking it: class: "three-by-four fullscreen"

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.

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

There are two types of buttons that can be used:

Buttons with type: "web_url" create a button that functions as a basic link: it opens the given URL in the web browser.

Buttons with type: "event" create a button that triggers an event, which can be caught in your bot later on. 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

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

You can show a gallery to the user by using the gallery_template builder function and passing it to 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

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.

When a gallery is opened in a modal (on web), it is possible to hide the modal when the button is clicked. Pass hide_modal: true to the button to achieve this.

On the web it is also possible to disable the modal entirely by adding modal: false to the card variable:

show gallery_template([item], modal: false)

Card template

A card template is basically a gallery with just one element. It is only available in its dynamic form:

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

As with gallery_template() it is also possible (on web) to disable the modal by adding modal: false to the card variable.

Card template is only available on web and on Google Assistant.

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.

Inline input widgets (inline forms)

On web, it is also possible to use any of the Input Widgets as an argument to show. This way, you can for example show an inline form in the chat stream without blocking the user interface:

The code for this is show input_method("form", …):

dialog form_demo
  say "You can leave your e-mail address if you want."
  show input_method("form", @address)
end

dialog event: "$form" do
  user.email = event.payload.email
  say "Thanks! I can now reach you on #{user.email}"
end

A submit of this form will cause an event to be fired. This event can be named by defining the property event in the form definition. Otherwise the default event name "$form" is used. Example of a YAML file used for an inline form (form.yaml):

caption: "Feel free to provide your email in case we get disconnected"
height: "compact"
event: "lead_capture"
schema:
  type: "object"
  properties:
    privacy_terms:
      type: boolean
      title: " I agree to the [privacy terms](https://www.botsquad.com/privacy)"
    email_notifications:
      type: boolean
      title: " I agree to receive notification emails"
    email:
      type: string
      format: "email"
      title: "Email"
  required: ["privacy_terms"]
ui_schema:
  email:
    ui:placeholder: "your@email.com"
    ui:autofocus: true
  ui:order: ["privacy_terms", "email_notifications", "email", "*"]

Example of corresponding BubbleScript code:

dialog show_form do
  show input_method("form", @form)
end

dialog event: "lead_capture" do
  user.privacy_terms = event.payload.privacy_terms
  user.email_notifations = event.payload.email_notifications
  user.email = event.payload.email
  remember user
end