IntentDialog class
Identifies a users intent and optionally extracts entities from a users utterance.
- Extends
Constructors
| Intent |
Constructs a new instance of an IntentDialog. |
Methods
| add |
Called once for each dialog within a library to give the dialog a chance to add its
|
| begin<T>(Session, T) | Called when a new dialog session is being started. |
| begin |
Binds an action to the dialog that will start another dialog anytime it's triggered. The new dialog will be pushed onto the stack so it does not automatically end the current task. The current task will be continued once the new dialog ends. The built-in prompts will automatically re-prompt the user once this happens but that behaviour can be disabled by setting the promptAfterAction flag when calling a built-in prompt. |
| cancel |
Binds an action to the dialog that will cancel the dialog anytime it's triggered. When canceled, the dialogs parent will be resumed with a resumed code indicating that it was canceled. |
| clone(Action |
Returns a clone of an existing ActionSet. |
| custom |
Binds a custom action to the dialog that will call the passed in onSelectAction handler when triggered. |
| dialog |
Called when a root dialog is being interrupted by another dialog. This gives the dialog that's being interrupted a chance to run custom logic before it's removed from the stack. The dialog itself is responsible for clearing the dialog stack and starting the new dialog. |
| dialog |
A child dialog has ended and the current one is being resumed. |
| end |
Binds an action that will end the conversation with the user when triggered. |
| find |
Called during the Library.findRoutes() call for each dialog on the stack to determine if any of the dialogs actions are triggered by the users utterance. |
| matches(Reg |
Invokes a handler when a given intent is detected in the users utterance.
|
| matches |
Invokes a handler when any of the given intents are detected in the users utterance.
|
| on |
Called when the dialog is first loaded after a call to session.beginDialog(). This gives the bot an opportunity to process arguments passed to the dialog. Handlers should always call the |
| on |
The default handler to invoke when there are no handlers that match the users intent.
|
| recognize(IRecognize |
Parses the users utterance and assigns a score from 0.0 - 1.0 indicating how confident the dialog is that it understood the users utterance. This method is always called for the active dialog on the stack. A score of 1.0 will indicate a perfect match and terminate any further recognition. When the score is less than 1.0, every dialog on the stack will have its recognizeAction() method called as well to see if there are any named actions bound to the dialog that better matches the users utterance. Global actions registered at the bot level will also be evaluated. If the dialog has a score higher then any bound actions, the dialogs replyReceived() method will be called with the result object returned from the recognize() call. This lets the dialog pass additional data collected during the recognize phase to the replyReceived() method for handling. Should there be an action with a higher score then the dialog the action will be invoked instead of the dialogs replyReceived() method. The dialog will stay on the stack and may be resumed at some point should the action invoke a new dialog so dialogs should prepare for unexpected calls to dialogResumed(). |
| recognizer(IIntent |
Adds a new recognizer plugin to the intent dialog. |
| reload |
Binds an action to the dialog that will cause the dialog to be reloaded anytime it's triggered. This is useful to implement logic that handle user utterances like "start over". |
| reply |
Processes messages received from the user. Called by the dialog system. |
| select |
Selects the route that had the highest confidence score for the utterance. |
| trigger |
Binds an action to the dialog that will make it the active dialog anytime it's triggered. The default behaviour is to interupt any existing dialog by clearing the stack and starting the dialog at the root of the stack. The dialog being interrupted can intercept this interruption by adding a custom onInterrupted handler to their trigger action options. Additionally, you can customize the way the triggered dialog is started by providing a custom onSelectAction handler to your trigger action options. |
Constructor Details
IntentDialog(IIntentDialogOptions)
Constructs a new instance of an IntentDialog.
new IntentDialog(options?: IIntentDialogOptions)Parameters
- options
- IIntentDialogOptions
(Optional) options used to initialize the dialog.
Method Details
addDialogTrigger(ActionSet, string)
Called once for each dialog within a library to give the dialog a chance to add its
triggerAction() to the libraries global action set. These triggers get mapped to
a beginDialogAction() that starts the dialog when the trigger condition is met.
function addDialogTrigger(actions: ActionSet, dialogId: string)Parameters
- actions
- ActionSet
Libraries global action set.
- dialogId
-
string
The fully qualified ID of the dialog to trigger.
begin<T>(Session, T)
Called when a new dialog session is being started.
function begin<T>(session: Session, args?: T)Parameters
- session
- Session
Session object for the current conversation.
- args
-
T
(Optional) arguments passed to the dialog by its parent.
beginDialogAction(string, string, IBeginDialogActionOptions)
Binds an action to the dialog that will start another dialog anytime it's triggered. The new dialog will be pushed onto the stack so it does not automatically end the current task. The current task will be continued once the new dialog ends. The built-in prompts will automatically re-prompt the user once this happens but that behaviour can be disabled by setting the promptAfterAction flag when calling a built-in prompt.
function beginDialogAction(name: string, id: string, options?: IBeginDialogActionOptions)Parameters
- name
-
string
Unique name to assign the action.
- id
-
string
ID of the dialog to start.
- options
- IBeginDialogActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action. You can also use dialogArgs to pass additional params to the dialog being started.
Returns
cancelAction(string, TextOrMessageType, ICancelActionOptions)
Binds an action to the dialog that will cancel the dialog anytime it's triggered. When canceled, the dialogs parent will be resumed with a resumed code indicating that it was canceled.
function cancelAction(name: string, msg?: TextOrMessageType, options?: ICancelActionOptions)Parameters
- name
-
string
Unique name to assign the action.
(Optional) message to send the user prior to canceling the dialog.
- options
- ICancelActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action.
Returns
clone(ActionSet)
Returns a clone of an existing ActionSet.
function clone(copyTo?: ActionSet)Parameters
- copyTo
- ActionSet
(Optional) instance to copy the current object to. If missing a new instance will be created.
Returns
customAction(IDialogActionOptions)
Binds a custom action to the dialog that will call the passed in onSelectAction handler when triggered.
function customAction(options: IDialogActionOptions)Parameters
- options
- IDialogActionOptions
The options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action. Custom matching logic can be provided using onFindAction.
Returns
dialogInterrupted(Session, string, any)
Called when a root dialog is being interrupted by another dialog. This gives the dialog that's being interrupted a chance to run custom logic before it's removed from the stack. The dialog itself is responsible for clearing the dialog stack and starting the new dialog.
function dialogInterrupted(session: Session, dialogId: string, dialogArgs: any)Parameters
- session
- Session
Session object for the current conversation.
- dialogId
-
string
ID of the dialog that should be started.
- dialogArgs
-
any
Arguments that should be passed to the new dialog.
dialogResumed<T>(Session, IDialogResult<T>)
A child dialog has ended and the current one is being resumed.
function dialogResumed<T>(session: Session, result: IDialogResult<T>)Parameters
- session
- Session
Session object for the current conversation.
- result
Result returned by the child dialog.
endConversationAction(string, TextOrMessageType, ICancelActionOptions)
Binds an action that will end the conversation with the user when triggered.
function endConversationAction(name: string, msg?: TextOrMessageType, options?: ICancelActionOptions)Parameters
- name
-
string
Unique name to assign the action.
(Optional) message to send the user prior to ending the conversation.
- options
- ICancelActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action.
Returns
findActionRoutes(IRecognizeDialogContext, (err: Error, results: IRouteResult[]) => void)
Called during the Library.findRoutes() call for each dialog on the stack to determine if any of the dialogs actions are triggered by the users utterance.
function findActionRoutes(context: IRecognizeDialogContext, callback: (err: Error, results: IRouteResult[]) => void)Parameters
- context
- IRecognizeDialogContext
The context of the incoming message as well as the dialogData for the evaluated dialog.
- callback
-
(err: Error, results: IRouteResult[]) => void
Function to invoke with the top candidate route(s).
matches(RegExp | string, string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)
Invokes a handler when a given intent is detected in the users utterance.
NOTE: The full details of the match, including the list of intents & entities detected, will be passed to the args of the first waterfall step or dialog that's started.
function matches(intent: RegExp | string, dialogId: string | IDialogWaterfallStep[] | IDialogWaterfallStep, dialogArgs?: any)Parameters
- intent
-
RegExp | string
- intent: {RegExp} - A regular expression that will be evaluated to detect the users intent.
- intent: {string} - A named intent returned by an IIntentRecognizer plugin that will be used to match the users intent.
- dialogId
-
string | IDialogWaterfallStep[] | IDialogWaterfallStep
- dialogId: _{string} - The ID of a dialog to begin when the intent is matched.
- dialogId: {IDialogWaterfallStep[]} - Waterfall of steps to execute when the intent is matched.
- dialogId: {IDialogWaterfallStep} - Single step waterfall to execute when the intent is matched. Calling a built-in prompt or starting a new dialog will result in the current dialog ending upon completion of the child prompt/dialog.
- dialogArgs
-
any
(Optional) arguments to pass the dialog that started when dialogId is a {string}.
Returns
matchesAny(RegExp[] | string[], string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)
Invokes a handler when any of the given intents are detected in the users utterance.
NOTE: The full details of the match, including the list of intents & entities detected, will be passed to the args of the first waterfall step or dialog that's started.
function matchesAny(intent: RegExp[] | string[], dialogId: string | IDialogWaterfallStep[] | IDialogWaterfallStep, dialogArgs?: any)Parameters
- intent
-
RegExp[] | string[]
- intent: {RegExp[]} - Array of regular expressions that will be evaluated to detect the users intent.
- intent: {string[]} - Array of named intents returned by an IIntentRecognizer plugin that will be used to match the users intent.
- dialogId
-
string | IDialogWaterfallStep[] | IDialogWaterfallStep
- dialogId: _{string} - The ID of a dialog to begin when the intent is matched.
- dialogId: {IDialogWaterfallStep[]} - Waterfall of steps to execute when the intent is matched.
- dialogId: {IDialogWaterfallStep} - Single step waterfall to execute when the intent is matched. Calling a built-in prompt or starting a new dialog will result in the current dialog ending upon completion of the child prompt/dialog.
- dialogArgs
-
any
(Optional) arguments to pass the dialog that started when dialogId is a {string}.
Returns
onBegin((session: Session, args: any, next: () => void) => void)
Called when the dialog is first loaded after a call to session.beginDialog(). This gives the bot an opportunity to process arguments passed to the dialog. Handlers should always call the next() function to continue execution of the dialogs main logic.
function onBegin(handler: (session: Session, args: any, next: () => void) => void)Parameters
- handler
-
(session: Session, args: any, next: () => void) => void
Function to invoke when the dialog begins.
Returns
onDefault(string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)
The default handler to invoke when there are no handlers that match the users intent.
NOTE: The full details of the recognition attempt, including the list of intents & entities detected, will be passed to the args of the first waterfall step or dialog that's started.
function onDefault(dialogId: string | IDialogWaterfallStep[] | IDialogWaterfallStep, dialogArgs?: any)Parameters
- dialogId
-
string | IDialogWaterfallStep[] | IDialogWaterfallStep
- dialogId: _{string} - The ID of a dialog to begin.
- dialogId: {IDialogWaterfallStep[]} - Waterfall of steps to execute.
- dialogId: {IDialogWaterfallStep} - Single step waterfall to execute. Calling a built-in prompt or starting a new dialog will result in the current dialog ending upon completion of the child prompt/dialog.
- dialogArgs
-
any
(Optional) arguments to pass the dialog that started when dialogId is a {string}.
Returns
recognize(IRecognizeDialogContext, (err: Error, result: IRecognizeResult) => void)
Parses the users utterance and assigns a score from 0.0 - 1.0 indicating how confident the dialog is that it understood the users utterance. This method is always called for the active dialog on the stack. A score of 1.0 will indicate a perfect match and terminate any further recognition. When the score is less than 1.0, every dialog on the stack will have its recognizeAction() method called as well to see if there are any named actions bound to the dialog that better matches the users utterance. Global actions registered at the bot level will also be evaluated. If the dialog has a score higher then any bound actions, the dialogs replyReceived() method will be called with the result object returned from the recognize() call. This lets the dialog pass additional data collected during the recognize phase to the replyReceived() method for handling.
Should there be an action with a higher score then the dialog the action will be invoked instead of the dialogs replyReceived() method. The dialog will stay on the stack and may be resumed at some point should the action invoke a new dialog so dialogs should prepare for unexpected calls to dialogResumed().
function recognize(context: IRecognizeDialogContext, callback: (err: Error, result: IRecognizeResult) => void)Parameters
- context
- IRecognizeDialogContext
The context of the request.
- callback
-
(err: Error, result: IRecognizeResult) => void
Function to invoke with the recognition results.
recognizer(IIntentRecognizer)
Adds a new recognizer plugin to the intent dialog.
function recognizer(plugin: IIntentRecognizer)Parameters
- plugin
- IIntentRecognizer
The recognizer to add.
Returns
reloadAction(string, TextOrMessageType, IBeginDialogActionOptions)
Binds an action to the dialog that will cause the dialog to be reloaded anytime it's triggered. This is useful to implement logic that handle user utterances like "start over".
function reloadAction(name: string, msg?: TextOrMessageType, options?: IBeginDialogActionOptions)Parameters
- name
-
string
Unique name to assign the action.
(Optional) message to send the user prior to reloading the dialog.
- options
- IBeginDialogActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action. You can also use dialogArgs to pass additional params to the dialog when reloaded.
Returns
replyReceived(Session, IRecognizeResult)
Processes messages received from the user. Called by the dialog system.
function replyReceived(session: Session, recognizeResult?: IRecognizeResult)Parameters
- session
- Session
Session object for the current conversation.
- recognizeResult
- IRecognizeResult
selectActionRoute(Session, IRouteResult)
Selects the route that had the highest confidence score for the utterance.
function selectActionRoute(session: Session, route: IRouteResult)Parameters
- session
- Session
Session object for the current conversation.
- route
- IRouteResult
Results returned from the call to findActionRoutes().
triggerAction(ITriggerActionOptions)
Binds an action to the dialog that will make it the active dialog anytime it's triggered. The default behaviour is to interupt any existing dialog by clearing the stack and starting the dialog at the root of the stack. The dialog being interrupted can intercept this interruption by adding a custom onInterrupted handler to their trigger action options. Additionally, you can customize the way the triggered dialog is started by providing a custom onSelectAction handler to your trigger action options.
function triggerAction(options: ITriggerActionOptions)Parameters
- options
- ITriggerActionOptions
Options used to configure the action.