Prompt for user input in the v3 JavaScript SDK

APPLIES TO: SDK v3

The Bot Framework SDK for Node.js provides a set of built-in prompts to simplify collecting inputs from a user.

A prompt is used whenever a bot needs input from the user. You can use prompts to ask a user for a series of inputs by chaining the prompts in a waterfall. You can use prompts in conjunction with waterfall to help you manage conversation flow in your bot.

This article will help you understand how prompts work and how you can use them to collect information from users.

Prompts and responses

Whenever you need input from a user, you can send a prompt, wait for the user to respond with input, and then process the input and send a response to the user.

The following code sample prompts the user for their name and responds with a greeting message.

bot.dialog('greetings', [
    // Step 1
    function (session) {
        builder.Prompts.text(session, 'Hi! What is your name?');
    },
    // Step 2
    function (session, results) {
        session.endDialog(`Hello ${results.response}!`);
    }
]);

Using this basic construct, you can model your conversation flow by adding as many prompts and responses as your bot requires.

Prompt results

Built-in prompts are implemented as dialogs that return the user's response in the results.response field. For JSON objects, responses are returned in the results.response.entity field. Any type of dialog handler can receive the result of a prompt. Once the bot receives a response, it can consume it or pass it back to the calling dialog by calling the session.endDialogWithResult method.

The following code sample shows how to return a prompt result to the calling dialog by using the session.endDialogWithResult method. In this example, the greetings dialog uses the prompt result that the askName dialog returns to greet the user by name.

// Ask the user for their name and greet them by name.
bot.dialog('greetings', [
    function (session) {
        session.beginDialog('askName');
    },
    function (session, results) {
        session.endDialog(`Hello ${results.response}!`);
    }
]);
bot.dialog('askName', [
    function (session) {
        builder.Prompts.text(session, 'Hi! What is your name?');
    },
    function (session, results) {
        session.endDialogWithResult(results);
    }
]);

Prompt types

The Bot Framework SDK for Node.js includes several different types of built-in prompts.

The following sections provide additional details about each type of prompt.

Prompts.text

Use the Prompts.text() method to ask the user for a string of text. The prompt returns the user's response as an IPromptTextResult.

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

Prompts.confirm

Use the Prompts.confirm() method to ask the user to confirm an action with a yes/no response. The prompt returns the user's response as an IPromptConfirmResult.

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

Prompts.number

Use the Prompts.number() method to ask the user for a number. The prompt returns the user's response as an IPromptNumberResult.

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

Prompts.time

Use the Prompts.time() method to ask the user for a time or date/time. The prompt returns the user's response as an IPromptTimeResult. The framework uses the Chrono library to parse the user's response and supports both relative responses (e.g., "in 5 minutes") and non-relative responses (e.g., "June 6th at 2pm").

The results.response field, which represents the user's response, contains an entity object that specifies the date and time. To resolve the date and time into a JavaScript Date object, use the EntityRecognizer.resolveTime() method.

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

Use the Prompts.choice() method to ask the user to choose from a list of options. The user can convey their selection either by entering the number associated with the option that they choose or by entering the name of the option that they choose. Both full and partial matches of the option's name are supported. The prompt returns the user's response as an IPromptChoiceResult.

To specify the style of the list that is presented to the user, set the IPromptOptions.listStyle property. The following table shows the ListStyle enumeration values for this property.

The ListStyle enum values are as follows:

You can access this enum from the builder object or you can provide an index to choose a ListStyle. For example, both statements in the following code snippet accomplish the same thing.

// ListStyle passed in as Enum
builder.Prompts.choice(session, "Which color?", "red|green|blue", { listStyle: builder.ListStyle.button });

// ListStyle passed in as index
builder.Prompts.choice(session, "Which color?", "red|green|blue", { listStyle: 3 });

To specify the list of options, you can use a pipe-delimited (|) string, an array of strings, or an object map.

A pipe-delimited string:

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

An array of strings:

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

An object map:

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

bot.dialog('getSalesData', [
    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 ${region.units} units for a total of ${region.total}.`); 
        } else {
            session.send("OK");
        }
    }
]);

Prompts.attachment

Use the Prompts.attachment() method to ask the user to upload a file such an image or video. The prompt returns the user's response as an IPromptAttachmentResult.

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

Next steps

Now that you know how to step users through a waterfall and prompt them for information, lets take a look at ways to help you better manage the conversation flow.