botbuilder-dialogs package

Reference

Classes

ChoiceFactory	A set of utility functions to assist with the formatting a 'message' activity containing a list of choices.
ComponentDialog	Base class for a dialog that contains other child dialogs.
Configurable	Base class for all configurable classes.
Dialog	Defines the core behavior for all dialogs.
DialogContainer	A container for a set of Dialogs.
DialogContext	The context for the current dialog turn with respect to a specific DialogSet.
DialogContextError	An Error that includes extra dialog context, including the dialog stack.
DialogEvents	Represents the events related to the "lifecycle" of the dialog.
DialogManager	Class which runs the dialog system.
DialogSet	A related set of dialogs that can all call each other.
DialogTurnStateConstants	Defines dialog turn state constants.
DialogsBotComponent	Bot component for bot Dialogs.
DialogsComponentRegistration	Makes dialogs component available to the system registering functionality.
DialogPath	Defines path for available dialogs.
DialogStateManager	The DialogStateManager manages memory scopes and path resolvers.
AliasPathResolver	Maps aliasXXX -> path.xxx ($foo => dialog.foo).
AtAtPathResolver	Maps @@ => turn.recognized.entitites.xxx array.
AtPathResolver	Maps @@ => turn.recognized.entitites.xxx[0]
DollarPathResolver	Maps $xxx => dialog.xxx
HashPathResolver	Maps #xxx => turn.recognized.intents.xxx
PercentPathResolver	Maps %xxx => class.xxx (aka activeDialog.properties.xxx)
ScopePath	Defines paths for the available scopes.
BotStateMemoryScope	Base class for memory scopes based on BotState.
ClassMemoryScope	ClassMemoryScope maps "class" -> dc.activeDialog.properties
ConversationMemoryScope	Memory that's scoped to the current conversation.
DialogClassMemoryScope	DialogClassMemoryScope maps "dialogClass" -> dc.parent.activeDialog.properties
DialogContextMemoryScope	`DialogContextMemoryScope` maps 'dialogcontext' -> properties.
DialogMemoryScope	DialogMemoryScope maps "dialog" -> dc.parent.activeDialog.state \|\| dc.activeDialog.state
MemoryScope	Abstract base class for all memory scopes.
SettingsMemoryScope	SettingsMemoryScope maps "settings" -> dc.context.turnState['settings']
ThisMemoryScope	ThisMemoryScope maps "this" -> dc.activeDialog.state
TurnMemoryScope	TurnMemoryScope represents memory scoped to the current turn.
UserMemoryScope	Memory that's scoped to the current user.
ThisPath	Defines path passed to the active dialog.
TurnPath	Defines path for avaiable turns.
ActivityPrompt	Waits for an activity to be received.
AttachmentPrompt	Prompts a user to upload attachments like images.
ChoicePrompt	Prompts a user to select from a list of choices.
ConfirmPrompt	Prompts a user to confirm something with a "yes" or "no" response.
DateTimePrompt	Prompts a user to enter a datetime expression.
NumberPrompt	Prompts a user to enter a number.
OAuthPrompt	Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service.
Prompt	Base class for all prompts.
PromptCultureModels	Class container for currently-supported Culture Models in Confirm and Choice Prompt.
TextPrompt	Prompts a user to enter some text.
Recognizer	Recognizer base class.
SkillDialog	A specialized Dialog that can wrap remote calls to a skill.
WaterfallDialog	A waterfall is a dialog that's optimized for prompting a user with a series of questions.
WaterfallStepContext	Context object passed in to a `WaterfallStep`.

Interfaces

BeginSkillDialogOptions	A class with dialog arguments for a SkillDialog.
ChoiceFactoryOptions	Additional options used to tweak the formatting of choice lists.
Choice	An instance of a choice that can be used to render a choice to a user or recognize something a user picked.
FindChoicesOptions	Options to control the recognition performed by `findChoices()`.
FoundChoice	Result returned by `findChoices()`.
FindValuesOptions	Basic search options used to control how choices are recognized in a users utterance.
FoundValue	INTERNAL: Raw search result returned by `findValues()`.
SortedValue	INTERNAL: A value that can be sorted and still refer to its original position within a source array. The `findChoices()` function expands the passed in choices to individual `SortedValue` instances and passes them to `findValues()`. Each individual `Choice` can result in multiple synonyms that should be searched for so this data structure lets us pass each synonym as a value to search while maintaining the index of the choice that value came from.
ModelResult	Outer result returned by an entity recognizer like `recognizeChoices()`.
Token	Individual token returned by a `TokenizerFunction`.
Converter	The converter converts object from one type to another.
DialogConfiguration
DialogEvent
DialogInstance	Contains state information for an instance of a dialog on the stack.
DialogTurnResult	Represents the result of a dialog context's attempt to begin, continue, or otherwise manipulate one or more dialogs.
DialogState	Contains dialog state, information about the state of the dialog stack, for a specific DialogSet.
DialogManagerConfiguration
DialogManagerResult
DialogDependencies
ComponentMemoryScopes	Interface for enumerating memory scopes.
ComponentPathResolvers	Interface for declaring path resolvers.
DialogStateManagerConfiguration
PathResolver	Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License.
ChoiceDefaultsChoicePrompt
ChoiceDefaultsConfirmPrompt
DateTimeResolution	Result returned by the `DateTimePrompt`.
OAuthPromptSettings	Settings used to configure an `OAuthPrompt` instance.
PromptOptions	Basic configuration options supported by all prompts.
PromptRecognizerResult	Result returned by a prompts recognizer function.
PromptValidatorContext	Contextual information passed to a custom `PromptValidator`.
PromptCultureModel
RecognizerConfiguration
SkillDialogOptions
TemplateInterface	Defines Template interface for binding data to T.
WaterfallStepInfo	Values passed to the `WaterfallStepContext` constructor.

Type Aliases

TokenizerFunction	Signature for an alternate word breaker that can be passed to `recognizeChoices()`, `findChoices()`, or `findValues()`. `type TokenizerFunction = (text: string, locale?: string) => Token[];`
ConverterFactory
PromptValidator	Function signature for providing a custom prompt validator. `type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;`
WaterfallStep	Function signature of an individual waterfall step. `type WaterfallStep<O extends object = {}> = (step: WaterfallStepContext<O>) => Promise<DialogTurnResult>;`

Enums

DialogReason

Indicates why a dialog method is being called.

DialogTurnStatus

Represents the state of the dialog stack after a dialog context attempts to begin, continue, or otherwise manipulate one or more dialogs. See also

ListStyle

Controls the way that choices for a ChoicePrompt or yes/no options for a ConfirmPrompt are presented to a user.

Functions

findChoices(string, string \| Choice[], FindChoicesOptions)	Mid-level search function for recognizing a choice in an utterance.
findValues(string, SortedValue[], FindValuesOptions)	INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level functions like `findChoices()` and `recognizeChoices()` are layered above this function. In most cases its easier to just call one of the higher level functions instead but this function contains the fuzzy search algorithm that drives choice recognition.
recognizeChoices(string, string \| Choice[], FindChoicesOptions)	High level function for recognizing a choice in a users utterance.
defaultTokenizer(string, string)	Simple tokenizer that breaks on spaces and punctuation.
getActiveDialogContext(DialogContext)	Recursively walk up the DC stack to find the active DC.
internalRun(TurnContext, string, DialogContext, DialogStateManagerConfiguration)
isFromParentToSkill(TurnContext)	Determines if the skill is acting as a skill parent.
runDialog(Dialog, TurnContext, StatePropertyAccessor<DialogState>)	Runs a dialog from a given context and accessor.
shouldSendEndOfConversationToParent(TurnContext, DialogTurnResult)	Helper to determine if we should send an EoC to the parent or not.
isComponentMemoryScopes(unknown)	Check if a ComponentRegistration is ComponentMemoryScopes or not.
isComponentPathResolvers(unknown)	Check if a ComponentRegistration is ComponentPathResolvers or not.
createConnectorClient(TurnContext, string, ClaimsIdentity, string)
exchangeToken(TurnContext, OAuthPromptSettings, TokenExchangeRequest)
getSignInResource(TurnContext, OAuthPromptSettings)
getUserToken(TurnContext, OAuthPromptSettings, string)
signOutUser(TurnContext, OAuthPromptSettings)

Function Details

findChoices(string, string | Choice[], FindChoicesOptions)

Mid-level search function for recognizing a choice in an utterance.

function findChoices(utterance: string, choices: string | Choice[], options?: FindChoicesOptions): ModelResult<FoundChoice>[]

Parameters

utterance: string

The text or user utterance to search over. For an incoming 'message' activity you can simply use context.activity.text.

choices: string | Choice[]

List of choices to search over.

options: FindChoicesOptions

(Optional) options used to tweak the search that's performed.

Returns

ModelResult<FoundChoice>[]

A list of found choices, sorted by most relevant first.

Remarks

This function is layered above findValues() and simply determines all of the synonyms that should be searched for before calling findValues() to perform the actual search. The recognizeChoices() function is layered above this function and adds the ability to select a choice by index or ordinal position in the list. Calling this particular function is useful when you don't want the index and ordinal position recognition done by recognizeChoices().

const { findChoices } = require('botbuilder-choices');

const choices = ['red', 'green', 'blue'];
const utterance = context.activity.text;
const results = findChoices(utterance, choices);
if (results.length == 1) {
    await context.sendActivity(`I like ${results[0].resolution.value} too!`);
} else if (results.length > 1) {
    const ambiguous = results.map((r) => r.resolution.value);
    await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`));
} else {
    await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`));
}

findValues(string, SortedValue[], FindValuesOptions)

INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level functions like findChoices() and recognizeChoices() are layered above this function. In most cases its easier to just call one of the higher level functions instead but this function contains the fuzzy search algorithm that drives choice recognition.

function findValues(utterance: string, values: SortedValue[], options?: FindValuesOptions): ModelResult<FoundValue>[]

Parameters

utterance: string

The text or user utterance to search over.

values: SortedValue[]

List of values to search over.

options: FindValuesOptions

(Optional) options used to tweak the search that's performed.

Returns

ModelResult<FoundValue>[]

A list of found values.

recognizeChoices(string, string | Choice[], FindChoicesOptions)

High level function for recognizing a choice in a users utterance.

function recognizeChoices(utterance: string, choices: string | Choice[], options?: FindChoicesOptions): ModelResult<FoundChoice>[]

Parameters

utterance: string

The text or user utterance to search over. For an incoming 'message' activity you can simply use context.activity.text.

choices: string | Choice[]

List of choices to search over.

options: FindChoicesOptions

(Optional) options used to tweak the search that's performed.

Returns

ModelResult<FoundChoice>[]

A list of found choices, sorted by most relevant first.

Remarks

This is layered above the findChoices() function and adds logic to let the user specify their choice by index (they can say "one" to pick choice[0]) or ordinal position (they can say "the second one" to pick choice[1].) The users utterance is recognized in the following order:

By name using findChoices().
By 1's based ordinal position.
By 1's based index position.

const { recognizeChoices } = require('botbuilder-choices');

const choices = ['red', 'green', 'blue'];
const utterance = context.activity.text;
const results = recognizeChoices(utterance, choices);
if (results.length == 1) {
    await context.sendActivity(`I like ${results[0].resolution.value} too!`);
} else if (results.length > 1) {
    const ambiguous = results.map((r) => r.resolution.value);
    await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`));
} else {
    await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`));
}

defaultTokenizer(string, string)

Simple tokenizer that breaks on spaces and punctuation.

function defaultTokenizer(text: string, _locale?: string): Token[]

Parameters

text: string

The input text.

_locale: string

Optional, identifies the locale of the input text.

Returns

Token[]

A list of tokens.

Remarks

The only normalization done is to lowercase the tokens. Developers can wrap this tokenizer with their own function to perform additional normalization like stemming.

const { recognizeChoices, defaultTokenizer } = require('botbuilder-choices');
const stemmer = require('stemmer');

function customTokenizer(text, locale) {
   const tokens = defaultTokenizer(text, locale);
   tokens.forEach((t) => {
       t.normalized = stemmer(t.normalized);
   });
   return tokens;
}

const choices = ['red', 'green', 'blue'];
const utterance = context.activity.text;
const results = recognizeChoices(utterance, choices, { tokenizer: customTokenizer });

getActiveDialogContext(DialogContext)

Recursively walk up the DC stack to find the active DC.

function getActiveDialogContext(dialogContext: DialogContext): DialogContext

Parameters

dialogContext: DialogContext

(xref:botbuilder-dialogs.DialogContext) for the current turn of conversation with the user.

Returns

DialogContext

Active DialogContext.

internalRun(TurnContext, string, DialogContext, DialogStateManagerConfiguration)

function internalRun(context: TurnContext, dialogId: string, dialogContext: DialogContext, dialogStateManagerConfiguration?: DialogStateManagerConfiguration): Promise<DialogTurnResult>

Parameters

context: TurnContext

The TurnContext for the turn.

dialogId: string

The dialog ID.

dialogContext: DialogContext

The DialogContext for the current turn of conversation.

dialogStateManagerConfiguration: DialogStateManagerConfiguration

Configuration for the dialog state manager.

Returns

Promise<DialogTurnResult>

a promise resolving to the dialog turn result.

isFromParentToSkill(TurnContext)

Determines if the skill is acting as a skill parent.

function isFromParentToSkill(context: TurnContext): boolean

Parameters

context: TurnContext

(xref:botbuilder-core.TurnContext) object for the current turn of conversation with the user.

Returns

boolean

A boolean representing if the skill is acting as a skill parent.

runDialog(Dialog, TurnContext, StatePropertyAccessor<DialogState>)

Runs a dialog from a given context and accessor.

function runDialog(dialog: Dialog, context: TurnContext, accessor: StatePropertyAccessor<DialogState>): Promise<void>

Parameters

dialog: Dialog

The Dialog to run.

context: TurnContext

(xref:botbuilder-core.TurnContext) object for the current turn of conversation with the user.

accessor: StatePropertyAccessor<DialogState>

Defined methods for accessing the state property created in a BotState object.

Returns

Promise<void>

shouldSendEndOfConversationToParent(TurnContext, DialogTurnResult)

Helper to determine if we should send an EoC to the parent or not.

function shouldSendEndOfConversationToParent(context: TurnContext, turnResult: DialogTurnResult): boolean

Parameters

context: TurnContext

The TurnContext for the turn.

turnResult: DialogTurnResult

The dialog turn result.

Returns

boolean

True if should send EoC, otherwise false.

isComponentMemoryScopes(unknown)

Check if a ComponentRegistration is ComponentMemoryScopes or not.

function isComponentMemoryScopes(component: unknown): boolean

Parameters

component: unknown

The component registration.

Returns

boolean

Type check result.

isComponentPathResolvers(unknown)

Check if a ComponentRegistration is ComponentPathResolvers or not.

function isComponentPathResolvers(component: unknown): boolean

Parameters

component: unknown

The component registration.

Returns

boolean

Type check result.

createConnectorClient(TurnContext, string, ClaimsIdentity, string)

function createConnectorClient(context: TurnContext, serviceUrl: string, claimsIdentity: ClaimsIdentity, audience: string): Promise<ConnectorClient>

Parameters

context: TurnContext

serviceUrl: string

claimsIdentity: ClaimsIdentity

audience: string

Returns

Promise<ConnectorClient>

exchangeToken(TurnContext, OAuthPromptSettings, TokenExchangeRequest)

function exchangeToken(context: TurnContext, settings: OAuthPromptSettings, tokenExchangeRequest: TokenExchangeRequest): Promise<TokenResponse>

Parameters

context: TurnContext

settings: OAuthPromptSettings

tokenExchangeRequest: TokenExchangeRequest

Returns

Promise<TokenResponse>

getSignInResource(TurnContext, OAuthPromptSettings)

function getSignInResource(context: TurnContext, settings: OAuthPromptSettings): Promise<SignInUrlResponse>

Parameters

context: TurnContext

settings: OAuthPromptSettings

Returns

Promise<SignInUrlResponse>

getUserToken(TurnContext, OAuthPromptSettings, string)

function getUserToken(context: TurnContext, settings: OAuthPromptSettings, magicCode: string): Promise<TokenResponse>

Parameters

context: TurnContext

settings: OAuthPromptSettings

magicCode: string

Returns

Promise<TokenResponse>

signOutUser(TurnContext, OAuthPromptSettings)

function signOutUser(context: TurnContext, settings: OAuthPromptSettings): Promise<void>

Parameters

context: TurnContext

settings: OAuthPromptSettings

Returns

Promise<void>

botbuilder-dialogs package

Classes

Interfaces

Type Aliases

Enums

Functions

Function Details

findChoices(string, string | Choice[], FindChoicesOptions)

Parameters

Returns

Remarks

findValues(string, SortedValue[], FindValuesOptions)

Parameters

Returns

recognizeChoices(string, string | Choice[], FindChoicesOptions)

Parameters

Returns

Remarks

defaultTokenizer(string, string)

Parameters

Returns

Remarks

getActiveDialogContext(DialogContext)

Parameters

Returns

internalRun(TurnContext, string, DialogContext, DialogStateManagerConfiguration)

Parameters

Returns

isFromParentToSkill(TurnContext)

Parameters

Returns

runDialog(Dialog, TurnContext, StatePropertyAccessor<DialogState>)

Parameters

Returns

shouldSendEndOfConversationToParent(TurnContext, DialogTurnResult)

Parameters

Returns

isComponentMemoryScopes(unknown)

Parameters

Returns

isComponentPathResolvers(unknown)

Parameters

Returns

createConnectorClient(TurnContext, string, ClaimsIdentity, string)

Parameters

Returns

exchangeToken(TurnContext, OAuthPromptSettings, TokenExchangeRequest)

Parameters

Returns

getSignInResource(TurnContext, OAuthPromptSettings)

Parameters

Returns

getUserToken(TurnContext, OAuthPromptSettings, string)

Parameters

Returns

signOutUser(TurnContext, OAuthPromptSettings)

Parameters

Returns

Additional resources