Prompts

Collecting Input

Bot Builder comes with a number of built-in prompts that can be used to collect input from a user.

Prompt Type Description
Prompts.text Asks the user to enter a string of text.
Prompts.confirm Asks the user to confirm an action.
Prompts.number Asks the user to enter a number.
Prompts.time Asks the user for a time or date.
Prompts.choice Asks the user to choose from a list of choices.
Prompts.attachment Asks the user to upload a picture or video.

These built-in prompts are implemented as a Dialog so they’ll return the users response through a call to session.endDialogWithresult(). Any DialogHandler can receive the result of a dialog but waterfalls tend to be the simplest way to handle a prompt result.

Prompts return to the caller an IPromptResult. The users response will be contained in the results.response field and may be null. There are a number of reasons for the response to be null. The built-in prompts let the user cancel an action by saying something like ‘cancel’ or ‘nevermind’ which will result in a null response. Or the user may fail to enter a properly formatted response which can also result in a null response. The exact reason can be determined by examining the ResumeReason returned in result.resumed.

Prompts.text()

The Prompts.text() method asks the user for a string of text. The users response will be returned as an IPromptTextResult.

builder.Prompts.text(session, "What is your name?");

Prompts.confirm()

The Prompts.confirm() method will ask the user to confirm an action with yes/no response. The users response will be returned as an IPromptConfirmResult.

builder.Prompts.confirm(session, "Are you sure you wish to cancel your order?");

Prompts.number()

The Prompts.number() method will ask the user to reply with a number. The users response will be returned as an IPromptNumberResult.

builder.Prompts.number(session, "How many would you like to order?");

Prompts.time()

The Prompts.time() method will ask the user to reply with a time. The users response will be returned as an IPromptTimeResult. The framework uses a library called Chrono to parse the users response and supports both relative “in 5 minutes” and non-relative “june 6th at 2pm” type responses.

The results.response returned is an entity that can be resolved into a JavaScript Date object using EntityRecognizer.resolveTime().

bot.dialog('/createAlarm', [
    function (session) {
        session.dialogData.alarm = {};
        builder.Prompts.text(session, "What would you like to name this alarm?");
    },
    function (session, results, next) {
        if (results.response) {
            session.dialogData.name = results.response;
            builder.Prompts.time(session, "What time would you like to set an alarm for?");
        } else {
            next();
        }
    },
    function (session, results) {
        if (results.response) {
            session.dialogData.time = builder.EntityRecognizer.resolveTime([results.response]);
        }
        
        // Return alarm to caller  
        if (session.dialogData.name && session.dialogData.time) {
            session.endDialogWithResult({ 
                response: { name: session.dialogData.name, time: session.dialogData.time } 
            }); 
        } else {
            session.endDialogWithResult({
                resumed: builder.ResumeReason.notCompleted
            });
        }
    }
]);

Prompts.choice()

The Prompts.choice() method asks the user to pick an option from a list. The users response will be returned as an IPromptChoiceResult. The list of choices can be presented to the user in a variety of styles via the IPromptOptions.listStyle property. The user can express their choice by either entering the number of the option or its name. Both full and partial matches of the options name are supported.

The list of choices can be passed to Prompts.choice() in a variety of ways. As a pipe ‘|’ delimited string.

builder.Prompts.choice(session, "Which color?", "red|green|blue");

As an array of strings.

builder.Prompts.choice(session, "Which color?", ["red","green","blue"]);

Or as an Object map. When an Object is passed in Objects keys will be used to determine the choices.

var salesData = {
    "west": {
        units: 200,
        total: "$6,000"
    },
    "central": {
        units: 100,
        total: "$3,000"
    },
    "east": {
        units: 300,
        total: "$9,000"
    }
};

bot.dialog('/', [
    function (session) {
        builder.Prompts.choice(session, "Which region would you like sales for?", salesData); 
    },
    function (session, results) {
        if (results.response) {
            var region = salesData[results.response.entity];
            session.send("We sold %(units)d units for a total of %(total)s.", region); 
        } else {
            session.send("ok");
        }
    }
]);

Prompts.attachment()

The Prompts.attachment() method will ask the user to upload a file attachment like an image or video. The users response will be returned as an IPromptAttachmentResult.

builder.Prompts.attachment(session, "Upload a picture for me to transform.");

Dialog Actions

Dialog actions offer shortcuts to implementing common actions. The DialogAction class provides a set of static methods that return a closure which can be passed to anything that accepts a dialog handler. This includes but is not limited to UniversalBot.dialog(), Library.dialog(), IntentDialog.matches(), and IntentDialog.onDefault().

Action Type Description
DialogAction.send Sends a static message to the user.
DialogAction.beginDialog Passes control of the conversation to a new dialog.
DialogAction.endDialog Ends the current dialog.
DialogAction.validatedPrompt Creates a custom prompt by wrapping one of the built-in prompts with a validation routine.