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

Lastly, we 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

Note: input widgets are currently only supported on the web platform. Other platforms do not show these widgets.

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.

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

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