Screens

Menus, inputs, routers and endings, and how a caller moves between them.

A menu shows a message, then its options numbered in order. The caller replies with a number and goes to that option's screen.

main_menu:
  type: menu
  text:
    en: "Welcome to Example Bank"
  options:
    - text: "Check Balance"
      next: enter_pin
    - text: "Exit"
      next: goodbye

The phone shows this as:

Welcome to Example Bank
1. Check Balance
2. Exit

You do not type the numbers into the message. If a message already lists its options, the editor moves them into the options below so there is one place to edit them.

Keys such as 0 and *

An option can have a key, such as 0 or *. Callers can then press that key as well as the option's number. The option is still shown with its number.

Add Back puts in a ready-made option: the text Back, the key *, going to a screen that leads to this menu. A menu you make from another screen, by dragging an exit onto empty space or choosing New screen… in a form, starts with that option already in place.

A message for a wrong choice

When a caller replies with something the menu does not offer, they see Invalid choice. Try again. and the menu again. Message for an invalid choice replaces that text.

Choices from data

A menu can list entries that come from an API instead of, or ahead of, options you type. See API calls and data.

Input

An input asks a question, checks the answer against its rules, and saves it under a name.

enter_pin:
  type: input
  text:
    en: "Enter your 4-digit PIN:"
  store_as: pin
  validators:
    - pattern: "^\\d{4}$"
      error: "PIN must be exactly 4 digits."
  max_attempts: 3
  on_max_attempts: locked_screen

Save the answer as names the variable. Later screens use it as {{pin}}, and conditions can test it.
Rules are checked in order. The first one the answer fails shows its message and asks again. A rule can also carry a condition on the answer, written with input, such as input|int <= 500.
Attempts limits how many wrong answers a caller gets, and says where they go after the last one. Left empty, they can keep trying.

Router

A router shows nothing. It runs its actions straight away, such as an API call, and moves on to the first condition that matches, or to its fallback.

check_account:
  type: router
  transitions:
    - actions:
        - type: http
          method: GET
          url: "{{api_base}}/accounts/{{phone_number}}"
          store_as: account
      guards:
        - when: "account.status == 200"
          next: main_menu
      default: not_registered

Use a router at the start of a flow to look the caller up before the first menu, or anywhere a decision needs no question.

End

An end screen shows a final message and closes the session.

show_balance:
  type: end
  text:
    en: "Your balance is {{auth.balance}}. Goodbye."

Where to go next

Menus, inputs and routers all have Where to go next. A route can run actions, then go to the first condition that holds, else to its fallback.

On an input, the route runs after a valid answer.
On a router, it runs as soon as the caller arrives.
On a menu, it is optional. A route there overrides every option's own screen, so leave it empty unless all options should run the same actions.

Keep it short

Most networks show about 182 characters per screen, so keep each one under that.

A flow that needs longer screens, such as a statement, can turn on paging in its YAML. Long screens are then split into pages, with keys added for More and Back:

pagination:
  limit: 160