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.
| 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/time. |
| Prompts.choice | Asks the user to choose from a list of options. |
| Prompts.attachment | Asks the user to upload a picture or video. |
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.
Tip
The time that the user enters is converted to UTC time based upon the time zone of the server that hosts the bot. Since the server may be located in a different time zone than the user, be sure to take time zones into consideration. To convert date and time to the user's local time, consider asking the user what time zone they are in.
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:
| Index | Name | Description |
|---|---|---|
| 0 | none | No list is rendered. This is used when the list is included as part of the prompt. |
| 1 | inline | Choices are rendered as an inline list of the form "1. red, 2. green, or 3. blue". |
| 2 | list | Choices are rendered as a numbered list. |
| 3 | button | Choices are rendered as buttons for channels that support buttons. For other channels they will be rendered as text. |
| 4 | auto | The style is selected automatically based on the channel and number of options. |
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.