Botsquad documentation logo

Input widgets are specialized controls which can be presented to the user at any time, as part of the conversation.

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:

location

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.

intro2

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:

form

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 answer.data 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
items:
 - 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 answer.data 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:

Item picker

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

Location selector

The location input method takes the following options:

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.

Form

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:

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
schema:
  type: object
  properties:
    street:
      type: string
      title: Street
    city:
      type: string
      title: City
    method:
      type: string
      title: "Shipping method"
      enum: ["Airplane", "Boat"]
    comments:
      type: string
      title: "Note"
  required: ["street", "city"]
ui_schema:
  ui:order:
  - street
  - city
  - "*"
  comments:
    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:

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: