Bot.Builder.Community.Dialogs.Prompts

Prompts for Bot Builder v4 .NET SDK

Build status

Branch	Status	Recommended NuGet package version
master

Description

This is part of the Bot Builder Community Extensions project which contains various pieces of middleware, recognizers and other components for use with the Bot Builder .NET SDK v4.

This package contains additional prompts, beyond those offered out of the box by the Bot Builder v4 .NET SDK.

Currently the following Prompts are available;

Prompt	Description
Number with Unit	Prompt a user for Currency, Temperature, Age, Dimension (distance).
Adaptive Card	Prompt a user using an Adaptive Card.

Installation

Available via NuGet package Bot.Builder.Community.Dialogs.Prompts

Install into your project using the following command in the package manager;

    PM> Install-Package Bot.Builder.Community.Dialogs.Prompts

Usage

Below is example usage for each of the Prompts

Number with Unit Prompt

The Number with Unit Prompt allows you to prompt for the following types of number;

• Currency
• Temperature
• Age
• Dimension (e.g. miles / meters)

Internally the Prompt uses the Microsoft Text Recognizers NumberWithPrompt recognizer.

To use the Prompt, create a new instance of the Prompt, specifying the type of Prompt (e.g. currency) using the second parameter. Once you have created the instance of your Prompt, you can add it to your list of dialogs (e.g. within a ComponentDialog).

            var numberPrompt = new NumberWithUnitPrompt(
					"CurrencyPrompt", 
					NumberWithUnitPromptType.Currency, 
					defaultLocale: Culture.English);

Then, you can call the bot by specifying your PromptOptions and calling PromptAsync.

			var options = new PromptOptions 
				{ 
					Prompt = new Activity { Type = ActivityTypes.Message, Text = "Enter a currency." } 
				};
            await dc.PromptAsync("CurrencyPrompt", options, cancellationToken);

The Prompt will return a NumberWithUnitResult object. This object contains a Value (dynamic) and a Unit (string). For example, if a user enters "twenty three dollars" when you are using the Currency prompt type, the resulting NumberWithUnitResult object will have Unit: "Dollar", Value: "23". Below is an example of how you might use this result.

			var currencyPromptResult = (NumberWithUnitResult)results.Result;
			await turnContext.SendActivityAsync(MessageFactory.Text($"Bot received Value: {currencyPromptResult.Value}, Unit: {currencyPromptResult.Unit}"), cancellationToken);

Adaptive Card Prompt

Features

• Includes validation for specified required input fields
• Displays custom message if user replies via text and not card input
• Ensures input is only valid if it comes from the appropriate card (not one shown previous to prompt)

Usage

// Load an adaptive card
const cardJson = require('./adaptiveCard.json');
const card = CardFactory.adaptiveCard(cardJson);

// Configure settings - All optional
var promptSettings = new AdaptiveCardPromptSettings() {
    Card: card,
    InputFailMessage: 'Please fill out the adaptive card',
    RequiredInputIds: [
        'inputA',
        'inputB',
    ],
    MissingRequiredInputsMessage: 'The following inputs are required',
    AttemptsBeforeCardRedsiplayed: 5,
    PromptId: 'myCustomId'
}

// Initialize the prompt
var adaptiveCardPrompt = new AdaptiveCardPrompt('adaptiveCardPrompt', null, promptSettings);

// Add the prompt to your dialogs
dialogSet.add(adaptiveCardPrompt);

// Call the prompt
return await stepContext.prompt('adaptiveCardPrompt');

// Use the result
const result = stepContext.result;

Adaptive Cards

Card authors describe their content as a simple JSON object. That content can then be rendered natively inside a host application, automatically adapting to the look and feel of the host. For example, Contoso Bot can author an Adaptive Card through the Bot Framework, and when delivered to Cortana, it will look and feel like a Cortana card. When that same payload is sent to Microsoft Teams, it will look and feel like Microsoft Teams. As more host apps start to support Adaptive Cards, that same payload will automatically light up inside these applications, yet still feel entirely native to the app. Users win because everything feels familiar. Host apps win because they control the user experience. Card authors win because their content gets broader reach without any additional work.

The Bot Framework provides support for Adaptive Cards. See the following to learn more about Adaptive Cards.

• Adaptive card
• Send an Adaptive card

Getting Input Data From Adaptive Cards

In a TextPrompt, the user response is returned in the Activity.Text property, which only accepts strings. Because Adaptive Cards can contain multiple inputs, the user response is sent as a JSON object in Activity.Value, like so:

const activity = {
    [...]
    "value": {
        "inputA": "response A",
        "inputB": "response B",
        [...etc]
    }
}

Because of this, it can be a little difficult to gather user input using an Adaptive Card within a dialog. The AdaptiveCardPrompt allows you to do so easily and returns the JSON object user response in stepContext.result.