Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IDialogWaterfallStep

Signature for functions passed as steps to DialogAction.waterfall().

Waterfalls let you prompt a user for information using a sequence of questions. Each step of the waterfall can either execute one of the built-in Prompts, start a new dialog by calling session.beginDialog(), advance to the next step of the waterfall manually using skip(), or terminate the waterfall.

When either a dialog or built-in prompt is called from a waterfall step, the results from that dialog or prompt will be passed via the results parameter to the next step of the waterfall. Users can say things like "never mind" to cancel the built-in prompts so you should guard against that by at least checking for results.response before proceeding. A more detailed explanation of why the waterfall is being continued can be determined by looking at the code returned for results.resumed.

You can manually advance to the next step of the waterfall using the skip() function passed in. Calling skip({ response: "some text" }) with an IDialogResult lets you more accurately mimic the results from a built-in prompt and can simplify your overall waterfall logic.

You can terminate a waterfall early by either falling through every step of the waterfall using calls to skip() or simply not starting another prompt or dialog.

note: Waterfalls have a hidden last step which will automatically end the current dialog if if you call a prompt or dialog from the last step. This is useful where you have a deep stack of dialogs and want a call to session.endDialog() from the last child on the stack to end the entire stack. The close of the last child will trigger all of its parents to move to this hidden step which will cascade the close all the way up the stack. This is typically a desired behavior but if you want to avoid it or stop it somewhere in the middle you'll need to add a step to the end of your waterfall that either does nothing or calls something like session.send() which isn't going to advance the waterfall forward.

example

var bot = new builder.BotConnectorBot();
bot.add('/', [
    function (session) {
        builder.Prompts.text(session, "Hi! What's your name?");
    },
    function (session, results) {
        if (results && results.response) {
            // User answered question.
            session.send("Hello %s.", results.response);
        } else {
            // User said never mind.
            session.send("OK. Goodbye.");
        }
    }
]);

Hierarchy

  • IDialogWaterfallStep

Callable

  • Signature for functions passed as steps to DialogAction.waterfall().

    Waterfalls let you prompt a user for information using a sequence of questions. Each step of the waterfall can either execute one of the built-in Prompts, start a new dialog by calling session.beginDialog(), advance to the next step of the waterfall manually using skip(), or terminate the waterfall.

    When either a dialog or built-in prompt is called from a waterfall step, the results from that dialog or prompt will be passed via the results parameter to the next step of the waterfall. Users can say things like "never mind" to cancel the built-in prompts so you should guard against that by at least checking for results.response before proceeding. A more detailed explanation of why the waterfall is being continued can be determined by looking at the code returned for results.resumed.

    You can manually advance to the next step of the waterfall using the skip() function passed in. Calling skip({ response: "some text" }) with an IDialogResult lets you more accurately mimic the results from a built-in prompt and can simplify your overall waterfall logic.

    You can terminate a waterfall early by either falling through every step of the waterfall using calls to skip() or simply not starting another prompt or dialog.

    note: Waterfalls have a hidden last step which will automatically end the current dialog if if you call a prompt or dialog from the last step. This is useful where you have a deep stack of dialogs and want a call to session.endDialog() from the last child on the stack to end the entire stack. The close of the last child will trigger all of its parents to move to this hidden step which will cascade the close all the way up the stack. This is typically a desired behavior but if you want to avoid it or stop it somewhere in the middle you'll need to add a step to the end of your waterfall that either does nothing or calls something like session.send() which isn't going to advance the waterfall forward.

    Parameters

    • session: Session

      Session object for the current conversation.

    • Optional result: any | IDialogResult<any>
      • result: {any} - For the first step of the waterfall this will be null or the value of any arguments passed to the handler.
      • result: {IDialogResult} - For subsequent waterfall steps this will be the result of the prompt or dialog called in the previous step.
    • Optional skip: function

      Function used to manually skip to the next step of the waterfall.

        • Parameters

          • Optional results: IDialogResult<any>

            (Optional) results to pass to the next waterfall step. This lets you more accurately mimic the results returned from a prompt or dialog.

          Returns void

    Returns any

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method