Edit

Share via

WaterfallDialog class

  • Reference
Package:
botbuilder-dialogs

A waterfall is a dialog that's optimized for prompting a user with a series of questions.

Extends

Dialog<O>

Remarks

Waterfalls accept a stack of functions which will be executed in sequence. Each waterfall step can ask a question of the user and the user's response will be passed to the next step in the waterfall via step.result. A special step.value object can be used to persist values between steps:

const { ComponentDialog, WaterfallDialog, TextPrompt, NumberPrompt } = require('botbuilder-dialogs);

class FillProfileDialog extends ComponentDialog {
    constructor(dialogId) {
        super(dialogId);

        // Add control flow dialogs
        this.addDialog(new WaterfallDialog('start', [
            async (step) => {
                // Ask user their name
                return await step.prompt('namePrompt', `What's your name?`);
            },
            async (step) => {
                // Remember the users answer
                step.values['name'] = step.result;

                // Ask user their age.
                return await step.prompt('agePrompt', `Hi ${step.values['name']}. How old are you?`);
            },
            async (step) => {
                // Remember the users answer
                step.values['age'] = step.result;

                // End the component and return the completed profile.
                return await step.endDialog(step.values);
            }
        ]));

        // Add prompts
        this.addDialog(new TextPrompt('namePrompt'));
        this.addDialog(new NumberPrompt('agePrompt'))
    }
}
module.exports.FillProfileDialog = FillProfileDialog;

Constructors

WaterfallDialog(string, WaterfallStep<O>[])

Creates a new waterfall dialog containing the given array of steps.

Properties

id

Unique ID of the dialog. Sets the unique ID of the dialog.
telemetryClient

Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

Inherited Properties

EndOfTurn

Gets a default end-of-turn result.

Methods

addStep(WaterfallStep<O>)

Adds a new step to the waterfall.
beginDialog(DialogContext, O)

Called when the WaterfallDialog is started and pushed onto the dialog stack.
continueDialog(DialogContext)

Called when the WaterfallDialog is continued, where it is the active dialog and the user replies with a new Activity.
endDialog(TurnContext, DialogInstance, DialogReason)

Called when the dialog is ending.
getVersion()

Gets the dialog version, composed of the ID and number of steps.
resumeDialog(DialogContext, DialogReason, any)

Called when a child WaterfallDialog completed its turn, returning control to this dialog.

Inherited Methods

configure(Record<string, unknown>)

Fluent method for configuring the object.
getConverter(string)
onDialogEvent(DialogContext, DialogEvent)

Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.
repromptDialog(TurnContext, DialogInstance)

When overridden in a derived class, reprompts the user for input.

Constructor Details

WaterfallDialog(string, WaterfallStep<O>[])

Creates a new waterfall dialog containing the given array of steps.

new WaterfallDialog(dialogId: string, steps?: WaterfallStep<O>[])

Parameters

dialogId

string

Unique ID of the dialog within the component or set its being added to.

steps

WaterfallStep<O>[]

(Optional) array of asynchronous waterfall step functions.

Remarks

See the addStep() function for details on creating a valid step function.

Property Details

id

Unique ID of the dialog. Sets the unique ID of the dialog.

string id

Property Value

string

The Id for the dialog.

Remarks

This will be automatically generated if not specified.

telemetryClient

Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

BotTelemetryClient telemetryClient

Property Value

BotTelemetryClient

The BotTelemetryClient to use for logging.

Inherited Property Details

EndOfTurn

Gets a default end-of-turn result.

static EndOfTurn: DialogTurnResult

Property Value

DialogTurnResult

Remarks

This result indicates that a dialog (or a logical step within a dialog) has completed processing for the current turn, is still active, and is waiting for more input.

Inherited From Dialog.EndOfTurn

Method Details

addStep(WaterfallStep<O>)

Adds a new step to the waterfall.

function addStep(step: WaterfallStep<O>): this

Parameters

step

WaterfallStep<O>

Asynchronous step function to call.

Returns

this

Waterfall dialog for fluent calls to addStep().

Remarks

All step functions should be asynchronous and return a DialogTurnResult. The WaterfallStepContext passed into your function derives from DialogContext and contains numerous stack manipulation methods which return a DialogTurnResult so you can typically just return the result from the DialogContext method you call.

The step function itself can be either an asynchronous closure:

const helloDialog = new WaterfallDialog('hello');

helloDialog.addStep(async (step) => {
    await step.context.sendActivity(`Hello World!`);
    return await step.endDialog();
});

A named async function:

async function helloWorldStep(step) {
    await step.context.sendActivity(`Hello World!`);
    return await step.endDialog();
}

helloDialog.addStep(helloWorldStep);

Or a class method that's been bound to its this pointer:

helloDialog.addStep(this.helloWorldStep.bind(this));

beginDialog(DialogContext, O)

Called when the WaterfallDialog is started and pushed onto the dialog stack.

function beginDialog(dc: DialogContext, options?: O): Promise<DialogTurnResult>

Parameters

dc
DialogContext

The DialogContext for the current turn of conversation.

options

O

Optional, initial information to pass to the Dialog.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

If the task is successful, the result indicates whether the Dialog is still active after the turn has been processed by the dialog.

continueDialog(DialogContext)

Called when the WaterfallDialog is continued, where it is the active dialog and the user replies with a new Activity.

function continueDialog(dc: DialogContext): Promise<DialogTurnResult>

Parameters

dc
DialogContext

The DialogContext for the current turn of conversation.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog. The result may also contain a return value.

endDialog(TurnContext, DialogInstance, DialogReason)

Called when the dialog is ending.

function endDialog(context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void>

Parameters

context

TurnContext

Context for the current turn of conversation.

instance
DialogInstance

The instance of the current dialog.

reason
DialogReason

The reason the dialog is ending.

Returns

Promise<void>

getVersion()

Gets the dialog version, composed of the ID and number of steps.

function getVersion(): string

Returns

string

Dialog version, composed of the ID and number of steps.

resumeDialog(DialogContext, DialogReason, any)

Called when a child WaterfallDialog completed its turn, returning control to this dialog.

function resumeDialog(dc: DialogContext, reason: DialogReason, result?: any): Promise<DialogTurnResult>

Parameters

dc
DialogContext

The DialogContext for the current turn of the conversation.

reason
DialogReason

(xref:botbuilder-dialogs.DialogReason) why the dialog resumed.

result

any

Optional, value returned from the dialog that was called. The type of the value returned is dependent on the child dialog.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Inherited Method Details

configure(Record<string, unknown>)

Fluent method for configuring the object.

function configure(config: Record<string, unknown>): this

Parameters

config

Record<string, unknown>

Configuration settings to apply.

Returns

this

The Configurable after the operation is complete.

Inherited From Configurable.configure

getConverter(string) 

function getConverter(_property: string): Converter | ConverterFactory

Parameters

_property

string

The key of the conditional selector configuration.

Returns

Converter | ConverterFactory

The converter for the selector configuration.

Inherited From Configurable.getConverter

onDialogEvent(DialogContext, DialogEvent)

Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.

function onDialogEvent(dc: DialogContext, e: DialogEvent): Promise<boolean>

Parameters

dc
DialogContext

The dialog context for the current turn of conversation.

e
DialogEvent

The event being raised.

Returns

Promise<boolean>

True if the event is handled by the current dialog and bubbling should stop.

Inherited From Dialog.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

When overridden in a derived class, reprompts the user for input.

function repromptDialog(_context: TurnContext, _instance: DialogInstance): Promise<void>

Parameters

_context

TurnContext

The context object for the turn.

_instance
DialogInstance

Current state information for this dialog.

Returns

Promise<void>

Remarks

Derived dialogs that support validation and re-prompt logic should override this method. By default, this method has no effect.

The DialogContext calls this method when the current dialog should re-request input from the user. This method is implemented for prompt dialogs.

See also

Inherited From Dialog.repromptDialog