Skip to content

Input widgets

Input widgets are specialized controls which can be presented to the user at any time, as part of the conversation. They are presented as alternative keyboards, meaning that the normal input control is hidden and the input widget is shown instead.

For example, when your conversation needs to get a user's location, it is nice to present a specialized location picker widget for sending the location, which includes a map and the user's current position:

In another dialog, you might require the user to make a multiple-choice selection using checkboxes. You could use the item picker widget for this case.

We also might want to present an entire form to the user at once. We can use the form input method for that, which looks like this:

There are also input widgets for scanning QR codes and barcodes, which use the built-in camera of your mobile phone.

Note: input widgets are supported on all platforms that Botsquad connects to. However, on platforms other than the web, the input widgets are rendered in an external browser window, and a link is presented in the chat pointing to the web browser. In Facebook Messenger, the input widgets show in the native FB messenger webview.

Input widgets in Bubblescript

Input widgets are triggered by passing a special input method value to the expecting: clause of the ask statement:

  choices = input_method("item_picker",
    caption: "Please select",
    mode: "multiple",
    items: [
      [title: "Frontend developer", subtitle: "React, HTML, Javascript", value: "frontend"],
      [title: "Backend developer", subtitle: "Elixir, Erlang, bash…", value: "backend"],
      [title: "Marketing manager", subtitle: "Hubspot and Facebook marketing", value: "marketing"]
  ask "Which positions are you interesed in?", expecting: choices

The choices variable here is filled using the input_method function, which takes the input widget type as the first argument, and the configuration of the widget as the second argument.

When the user submits the input widget, the user's selection is stored in the variable.

Defining input widgets in data files

Instead of defining the widget in code like this, it is often easier to cleaner to create a YAML file and put the configuration in there:

  ask "Which positions are you interesed in?",
    expecting: input_method("item_picker", @item_picker)

Where the item_picker.yaml file contains:

caption: Please select
mode: multiple
 - title: Frontend developer
   value: frontend
 - title: Backend developer
   value: backend
 - title: Marketing manager
   value: marketing

Input method reference

The function input_method(method, options) constructs a data structure which triggers the showing of an input widget. It validates the given options at runtime, to ensure that the widgets can be presented in a sensible manner.

  # construct the item picker input widget
  choices = input_method("item_picker", items: ["A", "B", "C"])
  # feed it to 'ask'
  ask "Pick one item:", expecting: choices

The result of the input is stored in the variable. If this variable is empty (nil), the user has cancelled the input widget (by clicking the cross icon).

The currently supported input methods are "item_picker", "location" and "form". The options to these are described below.

Common properties

All input widgets have some options shared between them:

  • required — Whether we require a value from the user or not. When the input is not required, a close button is shown in the top-right corner, allowing the user to cancel the interaction.
  • default_value — The preset value for the widget
  • height — A string, describing the desired height of the widget. Either compact, tall or full. Defaults to compact.
  • caption — An optional caption which is displayed as a title bar on top of the widget.
  • class — An optional CSS class which is set on the input widget. Can be used to tweak the styling for a particular widget.

Item picker

The item_picker input method is a versatile widget which can be used in single and multiple selection mode.

  • mode — either single or multiple; defaults to single.
  • confirm — In the case of single, this is a boolean value which can be set to true to show a confirmation button to confirm selection of the item. Otherwise, clicking the item immediately picks it.
  • items — The array of items that the user can choose from. The list can be either a list of plain strings, or it can be a list of maps with value, title elements (and optionally a subtitle).

Location selector

The location input method takes the following options:

  • center — lat/lng coordinate that sets the initial position on the map
  • zoom — the initial zoom level, a number between 1 and 20. defaults to 12.

When triggered, the location selector asks permission to retrieve the user's location, and centers the map on that location. The center option is only used as fallback when the user has denied this permission.


The form input method presents an entire form to the user inside the conversation. This can be used to let the user answer multiple questions at once, for instance, to ask somebody for his address details.

Under the hood, this uses the React JSON Schema Form library. So most options described there are functional and usable in this input widget. The Form customization section especially, goes into detail on the available customization options.

The form input method takes the following options:

  • schema — The JSON schema that the form adheres to.
  • ui_schema — Extra user interface options for the schema, see Form customization.

Form example

An example of a form input (as it is depicted in the image further up) is the following:

  ask "Please enter your address", expecting: input_method("form", @address)

Where address.yaml contains:

caption: Shipping address
height: tall
  type: object
      type: string
      title: Street
      type: string
      title: City
      type: string
      title: "Shipping method"
      enum: ["Airplane", "Boat"]
      type: string
      title: "Note"
  required: ["street", "city"]
  - street
  - city
  - "*"
    ui:widget: textarea

QR code scanner

The qr input method shows a QR code scanner. It first asks the user permission to use the camera, and then shows a live camera view to scan a QR code. As soon as a QR code is found, a beeping sound will be heard and the conversation will continue.

The qr input method takes the following options:

  • confirm — if true, show a "confirm" button to confirm the code before the conversation continues.

Barcode scanner

The barcode input method shows a barcode scanner. It first asks the user permission to use the camera, and then shows a live camera view to scan a QR code. As soon as a barcode is found, a beeping sound will be heard and the conversation will continue.

Internally, we use the Quagga Javascript library to scan barcodes

The barcode input method takes the following options:

  • confirm — if true, show a "confirm" button to confirm the code before the conversation continues.
  • readers - a list of strings with the barcode types to search for. Defaults to ["code_128"], but can contain one or more of the following values:
  • code_128
  • ean
  • ean_8
  • code_39
  • code_39_vin
  • codabar
  • upc
  • upc_e
  • i2of5
  • 2of5
  • code_93