botbuilder-dialogs/lib/prompts/prompt.d.ts

A dialog stack based conversation manager for Microsoft BotBuilder.

/**
 * @module botbuilder-dialogs
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { Activity, TurnContext } from 'botbuilder-core';
import { Choice, ChoiceFactoryOptions } from '../choices';
import { Dialog, DialogInstance, DialogReason, DialogTurnResult, DialogEvent } from '../dialog';
import { DialogContext } from '../dialogContext';
/**
 * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are
 * presented to a user.
 */
export declare enum ListStyle {
    /**
     * Don't include any choices for prompt.
     */
    none = 0,
    /**
     * Automatically select the appropriate style for the current channel.
     */
    auto = 1,
    /**
     * Add choices to prompt as an inline list.
     */
    inline = 2,
    /**
     * Add choices to prompt as a numbered list.
     */
    list = 3,
    /**
     * Add choices to prompt as suggested actions.
     */
    suggestedAction = 4,
    /**
     * Add choices to prompt as a HeroCard with buttons.
     */
    heroCard = 5
}
/**
 * Basic configuration options supported by all prompts.
 */
export interface PromptOptions {
    /**
     * (Optional) Initial prompt to send the user.
     */
    prompt?: string | Partial<Activity>;
    /**
     * (Optional) Retry prompt to send the user.
     */
    retryPrompt?: string | Partial<Activity>;
    /**
     * (Optional) List of choices associated with the prompt.
     */
    choices?: (string | Choice)[];
    /**
     * (Optional) Property that can be used to override or set the value of ChoicePrompt.Style
     * when the prompt is executed using DialogContext.prompt.
     */
    style?: ListStyle;
    /**
     * (Optional) Additional validation rules to pass the prompts validator routine.
     */
    validations?: object;
}
/**
 * Result returned by a prompts recognizer function.
 *
 * @param T Type of value being recognized.
 */
export interface PromptRecognizerResult<T> {
    /**
     * If `true` the users utterance was successfully recognized and [value](#value) contains the
     * recognized result.
     */
    succeeded: boolean;
    /**
     * Value that was recognized if [succeeded](#succeeded) is `true`.
     */
    value?: T;
}
/**
 * Function signature for providing a custom prompt validator.
 *
 * ```TypeScript
 * type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;
 * ```
 *
 * @remarks
 * The validator should be an asynchronous function that returns `true` if
 * `prompt.recognized.value` is valid and the prompt should end.
 *
 * > [!NOTE]
 * > If the validator returns `false` the prompts default re-prompt logic will be run unless the
 * > validator sends a custom re-prompt to the user using `prompt.context.sendActivity()`. In that
 * > case the prompts default re-rpompt logic will not be run.
 * @param T Type of recognizer result being validated.
 * @param PromptValidator.prompt Contextual information containing the recognizer result and original options passed to the prompt.
 */
export declare type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;
/**
 * Contextual information passed to a custom `PromptValidator`.
 *
 * @param T Type of recognizer result being validated.
 */
export interface PromptValidatorContext<T> {
    /**
     * The context for the current turn of conversation with the user.
     *
     * @remarks
     * The validator can use this to re-prompt the user.
     */
    readonly context: TurnContext;
    /**
     * Result returned from the prompts recognizer function.
     *
     * @remarks
     * The `prompt.recognized.succeeded` field can be checked to determine of the recognizer found
     * anything and then the value can be retrieved from `prompt.recognized.value`.
     */
    readonly recognized: PromptRecognizerResult<T>;
    /**
     * A dictionary of values persisted for each conversational turn while the prompt is active.
     *
     * @remarks
     * The validator can use this to persist things like turn counts or other state information.
     */
    readonly state: object;
    /**
     * Original set of options passed to the prompt by the calling dialog.
     *
     * @remarks
     * The validator can extend this interface to support additional prompt options.
     */
    readonly options: PromptOptions;
    /**
     * A count of the number of times the prompt has been executed.
     *
     * A number indicating how many times the prompt was invoked (starting at 1 for the first time it was invoked).
     */
    readonly attemptCount: number;
}
/**
 * Base class for all prompts.
 *
 * @param T Type of value being returned by the prompts recognizer function.
 */
export declare abstract class Prompt<T> extends Dialog {
    private validator?;
    /**
     * Creates a new Prompt instance.
     *
     * @param dialogId Unique ID of the prompt within its parent `DialogSet` or `ComponentDialog`.
     * @param validator (Optional) custom validator used to provide additional validation and re-prompting logic for the prompt.
     */
    protected constructor(dialogId: string, validator?: PromptValidator<T>);
    /**
     * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
     *
     * @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current
     * turn of the conversation.
     * @param options Optional. [PromptOptions](xref:botbuilder-dialogs.PromptOptions),
     * additional information to pass to the prompt being started.
     * @returns A `Promise` representing the asynchronous operation.
     * @remarks
     * If the task is successful, the result indicates whether the prompt is still
     * active after the turn has been processed by the prompt.
     */
    beginDialog(dc: DialogContext, options: PromptOptions): Promise<DialogTurnResult>;
    /**
     * Called when a prompt dialog is the active dialog and the user replied with a new activity.
     *
     * @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
     * @returns 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 prompt generally continues to receive the user's replies until it accepts the
     * user's reply as valid input for the prompt.
     */
    continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
    /**
     * Called before an event is bubbled to its parent.
     *
     * @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
     * @param event [DialogEvent](xref:botbuilder-dialogs.DialogEvent), the event being raised.
     * @returns Whether the event is handled by the current dialog and further processing should stop.
     * @remarks
     * This is a good place to perform interception of an event as returning `true` will prevent
     * any further bubbling of the event to the dialogs parents and will also prevent any child
     * dialogs from performing their default processing.
     */
    protected onPreBubbleEvent(dc: DialogContext, event: DialogEvent): Promise<boolean>;
    /**
     * Called when a prompt dialog resumes being the active dialog on the dialog stack, such as
     * when the previous active dialog on the stack completes.
     *
     * @param dc The DialogContext for the current turn of the conversation.
     * @param _reason An enum indicating why the dialog resumed.
     * @param _result Optional, value returned from the previous dialog on the stack.
     * The type of the value returned is dependent on the previous dialog.
     * @returns 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.
     */
    resumeDialog(dc: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult>;
    /**
     * Called when a prompt dialog has been requested to re-prompt the user for input.
     *
     * @param context [TurnContext](xref:botbuilder-core.TurnContext), context for the current
     * turn of conversation with the user.
     * @param instance [DialogInstance](xref:botbuilder-dialogs.DialogInstance), the instance
     * of the dialog on the stack.
     * @returns A `Promise` representing the asynchronous operation.
     */
    repromptDialog(context: TurnContext, instance: DialogInstance): Promise<void>;
    /**
     * Called anytime the derived class should send the user a prompt.
     *
     * @param context Context for the current turn of conversation with the user.
     * @param state Additional state being persisted for the prompt.
     * @param options Options that the prompt was started with in the call to `DialogContext.prompt()`.
     * @param isRetry If `true` the users response wasn't recognized and the re-prompt should be sent.
     */
    protected abstract onPrompt(context: TurnContext, state: object, options: PromptOptions, isRetry: boolean): Promise<void>;
    /**
     * Called to recognize an utterance received from the user.
     *
     * @remarks
     * The Prompt class filters out non-message activities so its safe to assume that the users
     * utterance can be retrieved from `context.activity.text`.
     * @param context Context for the current turn of conversation with the user.
     * @param state Additional state being persisted for the prompt.
     * @param options Options that the prompt was started with in the call to `DialogContext.prompt()`.
     */
    protected abstract onRecognize(context: TurnContext, state: object, options: PromptOptions): Promise<PromptRecognizerResult<T>>;
    /**
     * Helper function to compose an output activity containing a set of choices.
     *
     * @param prompt The prompt to append the users choices to.
     * @param channelId ID of the channel the prompt is being sent to.
     * @param choices List of choices to append.
     * @param style Configured style for the list of choices.
     * @param options (Optional) options to configure the underlying ChoiceFactory call.
     * @returns The composed activity ready to send to the user.
     */
    protected appendChoices(prompt: string | Partial<Activity>, channelId: string, choices: (string | Choice)[], style: ListStyle, options?: ChoiceFactoryOptions): Partial<Activity>;
}
//# sourceMappingURL=prompt.d.ts.map