Resources »

Guides »

Bots »

Conversational Bots »

Prompting for user input

What are prompts?

A conversational bot can use prompt actions to ask for user input. The behavior will pause at that point until it receives a response.

The response to a prompt can determine the next step in a bot’s behavior.

Prompts were drastically simplified in the 8.3.1 update. You can now format, validate, and save a response within the prompt action itself. Previously, this functionality had to be implemented by hand.

Here’s an example prompt that asks a user to choose a number between 1 and 100:

This might look a little complicated at first – it’s packing a lot of functionality into a few free-form options.

Let’s look at each of these options in detail.

Prompt types

There are different types of prompts available depending on the information your bot needs to collect.

Rather than always requiring the user to type an answer, alternate prompts make it easier for them to respond in the right format.

Buttons

When prompting with buttons, the user selects from a pre-defined list of responses.

Configuring a button prompt

In a conversational bot behavior, add the Prompt With » Buttons action.

  • Options: A list of pre-defined responses that will be displayed as buttons. One response per line. You can use scripting to build the list.
  • Colors: You can configure a color gradient to automatically style the buttons. For instance, a satisfaction survey asking about sentiment could start green (positive) and end red (negative).
  • Custom CSS style: You can include custom CSS rules to further style the buttons. In the example above, we’re configuring a fixed width and allowing the buttons to display inline (i.e. adjacent rather than stacked).
  • Save the response to a placeholder named: See Saving placeholders
  • Format the placeholder with this template: See Formatting
  • Validate the placeholder with this template: See Validation

Chooser

When prompting with a chooser, the user selects one or more existing records using a helper popup or autocomplete text box.

Chooser prompts are currently only available when conversing with workers (opposed to portal visitors or mobile users).

Configuring a chooser prompt

In a conversational bot behavior, add the Prompt With » Chooser action.

  • Type: The record type to be selected.
  • Query: The default query to pre-filter records in the chooser popup.
  • Selection: Is the user able to select multiple records, or just one? If selecting a single record, the popup will automatically close after the first selection.
  • Autocomplete: Display an autocomplete textbox in addition to the chooser button. This is useful if the user may already know what they want to select, as they can bypass the chooser popup.
  • Save the response to a placeholder named: See Saving placeholders

Tips for chooser prompts

  • If the name your placeholder ends with _id then all of the placeholders for the selected record will be available. For instance, a placeholder like prompt_worker_id will be able to use prompt_worker__label and prompt_worker_first_name.

Date Input

When prompting with a date input, the user can enter an absolute (2020-12-31 08:00) or relative date (tomorrow 8am). A calendar popup can also be used to select a specific date.

If a relative date is given, it is automatically converted into an absolute date before sending. This ensures that the bot is always receiving the response to a date prompt in a consistent format.

Configuring a date prompt

In a conversational bot behavior, add the Prompt With » Date Input action.

  • Placeholder: The instructive text shown in the date prompt before any text is entered.
  • Default: The default text in the date prompt.
  • Save the response to a placeholder named: See Saving placeholders
  • Format the placeholder with this template: See Formatting
  • Validate the placeholder with this template: See Validation

File Upload

When prompting with a file upload, the user selects a file from their computer to share with the bot.

File upload prompts are currently only available when conversing with workers (opposed to portal visitors or mobile users).

Configuring a file upload prompt

In a conversational bot behavior, add the Prompt With » File Upload action.

Tips for file upload prompts

  • If the name your placeholder ends with _id then all of the placeholders for the uploaded file will be available. For instance, a placeholder like prompt_file_id will be able to use prompt_file_size and prompt_file_mime_type.

Images

When prompting with images, the user selects from a pre-defined list of responses represented by images.

Configuring an image prompt

In a conversational bot behavior, add the Prompt With » Images action.

  • Images: Click the (+) icon to add a new image-based response. Each response includes an image and a label.
    • Image: Upload or generate an image.
    • Label: Add a label for this image. This is the text response that will be sent when this image is selected.
  • Save the response to a placeholder named: See Saving placeholders
  • Format the placeholder with this template: See Formatting
  • Validate the placeholder with this template: See Validation

Text Input

When prompting with text input, the user is free to type anything.

Configuring a text prompt

In a conversational bot behavior, add the Prompt With » Text Input action.

  • Placeholder: The instructive text shown in the prompt before any text is entered.
  • Default: The default text in the prompt.
  • Options: Whether the text prompt accepts a single line of input, or multiple lines.
  • Save the response to a placeholder named: See Saving placeholders
  • Format the placeholder with this template: See Formatting
  • Validate the placeholder with this template: See Validation

Wait

The wait prompt is useful when your bot needs to run a potentially long-running action (e.g. remote API call) and you’d like to warn the user first.

Rather than leaving the working watching a loading spinner without an explanation, the bot can say “Let me check on that for you. This may take a moment…“, wait, and then run the action.

Configuring a wait prompt

In a conversational bot behavior, add the Prompt With » Wait action.

You don’t need to configure anything for a wait prompt. However, you can get creative with the responses that precede it. Using the random() function will add some variety to your bot.

Saving placeholders

In the Save the response to a placeholder named: option, you can name a placeholder where a copy of the user’s response will be saved.

You can then later refer to this answer when making decisions or giving responses.

Formatting

With Format the placeholder with this template:, you can format the user’s response before validating or saving it.

The formatting template has access to all of Cerb’s scripting functionality.

Examples

Format a number

This formats a number, removing thousands separators and decimal places:



{{message|replace({',':''})|number_format(0, '.', '')}}

Format a date as a Unix timestamp



{{message|date('U')}}

Validation

With Validate the placeholder with this template:, you can run multiple tests against the user’s response in a single template.

Any output from this template is considered to be an error that will be displayed to the worker. Cerb will take care of automatically repeating your prompt for you until valid input is given.

When the template returns no output, the response is considered to be valid and Cerb will save it to your placeholder.

The validate template also has access to all of Cerb’s scripting functionality.

Examples

Validate a date



{% set ts = message|date('U') %}
{% if 0 == ts %}
Please enter a valid date. For instance, "Friday noon".
{% elseif ts < 'now'|date('U') %}
Please enter a date in the future.
{% endif %}

Validate a number within a range



{% if message is not numeric %}
Please enter a valid number.
{% elseif message < 1 or message > 100 %}
The number must be between 1 and 100.
{% endif %}

Validate an email address



{% set email = message|parse_emails|first %}
{% if message is empty %}
Please enter an email address.
{% elseif email.host == 'localhost' %}
Please enter a valid email address.
{% endif %}

Next steps

You can import the Prompt Bot package for a fully working example.