PromptTime class

Customizable time prompt.

Extends

Constructors

PromptTime(IPromptFeatures)

Creates a new customizable instance of the prompt. Your new prompt should be added as a dialog to either a bot or library.

Properties

features

The prompts current configured set of features.

Methods

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.

begin<T>(Session, T)

Called when a new dialog session is being started.

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.

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.

clone(ActionSet)

Returns a clone of an existing ActionSet.

customAction(IDialogActionOptions)

Binds a custom action to the dialog that will call the passed in onSelectAction handler when triggered.

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.

dialogResumed<T>(Session, IDialogResult<T>)

A child dialog has ended and the current one is being resumed.

endConversationAction(string, TextOrMessageType, ICancelActionOptions)

Binds an action that will end the conversation with the user when triggered.

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.

formatMessage(Session, TextType, TextType, (err: Error, msg: IMessage) => void)

Creates the message to send for the prompt. This is called automatically by sendPrompt() so in most cases you'll want to register a onFormatMessage() handler to customize the message sent for a prompt. You should only need to call this method if you're implementing your own sendPrompt() logic.

gettext(Session, TextType, string)

Returns the text for a prompt that's been localized using the namespace of the prompts caller.

matches(RegExp | string, string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)

Invokes a handler when a given intent is detected in the users utterance. For string based intents, the intent can either be an intent returned by a recognizer() registered for the prompt or it can be an intent that flows in from a global recognizer().

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.

matchesAny(RegExp[] | string[], string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)

Invokes a handler when any of the given intents are detected in the users utterance. For string based intents, the intent can either be an intent returned by a recognizer() registered for the prompt or it can be an intent that flows in from a global recognizer().

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.

onFormatMessage((session: Session, text: TextType, speak: TextType, callback: (err: Error, message?: IMessage) => void) => void)

Registers a handler that will be called to create the outgoing IMessage that will be sent for the prompt. This handler is only called when the current prompt/retryPrompt is of type string|string[]. Anytime the prompt/retryPrompt is an IMessage|IIsMessage the configured message is used so your handler will not be called. Multiple handlers can be registered and the first handler to call callback() with a message will be used. Calling callback(null, null) will cause processing to move to the next handler in the chain.

onPrompt((session: Session, next: Function) => void)

Registers a handler that will be called every time the prompt is about to send a message to the user. You can use this hook to implement your own custom prompt sending logic. Multiple handlers can be registered and calling next() will invoke the next handler in the chain. The final handler performs the prompts default logic which is to create a new message using formatMessage() and then send it.

onRecognize((context: IRecognizeDialogContext, callback: (err: Error, score: number, response?: any) => void) => void)

Registers a handler that will be called everytime the prompt receives a reply from the user. The handlers callback() can be used to return a confidence score that it understood the users input as well as the value that should be returned to the caller of the prompt. Calling callback(null, 1.0, true); would indicate a high confidence that the user answered the prompt and would return a boolean true as the response from the prompt. Any response type is possible, including objects. Calling callback(null, 0.0); indicates that the users input was not understood at all and that they should be re-prompted.

Multiple handlers can be registered and unlike the other handler types, all of the registered will be called and handler providing the highest confidence score will be chosen as the winner. When customizing one of the built-in prompt types you'll often want to disable the prompts default recognizer logic. This can be achieved by setting the features of the prompt when you create it. Just keep in mind that if you completely disable the prompts default recognizer logic, you'll need to do all of the recognition yourself.

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().

recognizer(IIntentRecognizer)

Adds a new recognizer plugin to the Prompt which will be run everytime the user replies to the prompt.

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".

replyReceived(Session, IRecognizeResult)

Processes messages received from the user. Called by the dialog system.

selectActionRoute(Session, IRouteResult)

Selects the route that had the highest confidence score for the utterance.

sendPrompt(Session)

Sends a prompt to the user for the current turn. This can be called from a [matches()][#matches] handler to manually send a prompt/reprompt to the user. To force sending of the initial prompt you would need to set session.dialogData.turns = 0; before calling sendPrompt().

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.

Constructor Details

PromptTime(IPromptFeatures)

Creates a new customizable instance of the prompt. Your new prompt should be added as a dialog to either a bot or library.

new PromptTime(features?: IPromptFeatures)

Parameters

features
IPromptFeatures

(Optional) features used to customize the prompts behaviour.

Property Details

features

The prompts current configured set of features.

public features: IPromptFeatures

Property Value

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.

msg
TextOrMessageType

(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

IDialogResult<T>

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.

msg
TextOrMessageType

(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).

formatMessage(Session, TextType, TextType, (err: Error, msg: IMessage) => void)

Creates the message to send for the prompt. This is called automatically by sendPrompt() so in most cases you'll want to register a onFormatMessage() handler to customize the message sent for a prompt. You should only need to call this method if you're implementing your own sendPrompt() logic.

function formatMessage(session: Session, text: TextType, speak: TextType, callback: (err: Error, msg: IMessage) => void)

Parameters

session
Session

Session object for the current conversation.

text
TextType

Current prompt/retryPrompt text.

speak
TextType

Current speak/retrySpeak SSML. This value may be null.

callback

(err: Error, msg: IMessage) => void

Function to receive the created message.

gettext(Session, TextType, string)

Returns the text for a prompt that's been localized using the namespace of the prompts caller.

static function gettext(session: Session, text: TextType, namespace?: string)

Parameters

session
Session

Current session for the conversation.

text
TextType

Prompt to localize.

namespace

string

(Optional) library namespace to use for localizing the prompt. By default the namespace of the prompts caller will be used.

Returns

string

matches(RegExp | string, string | IDialogWaterfallStep[] | IDialogWaterfallStep, any)

Invokes a handler when a given intent is detected in the users utterance. For string based intents, the intent can either be an intent returned by a recognizer() registered for the prompt or it can be an intent that flows in from a global recognizer().

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. For string based intents, the intent can either be an intent returned by a recognizer() registered for the prompt or it can be an intent that flows in from a global recognizer().

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

onFormatMessage((session: Session, text: TextType, speak: TextType, callback: (err: Error, message?: IMessage) => void) => void)

Registers a handler that will be called to create the outgoing IMessage that will be sent for the prompt. This handler is only called when the current prompt/retryPrompt is of type string|string[]. Anytime the prompt/retryPrompt is an IMessage|IIsMessage the configured message is used so your handler will not be called. Multiple handlers can be registered and the first handler to call callback() with a message will be used. Calling callback(null, null) will cause processing to move to the next handler in the chain.

function onFormatMessage(handler: (session: Session, text: TextType, speak: TextType, callback: (err: Error, message?: IMessage) => void) => void)

Parameters

handler

(session: Session, text: TextType, speak: TextType, callback: (err: Error, message?: IMessage) => void) => void

Function that will be called to create an IMessage for the current prompt. Call callback() with either a message or null to continue processing.

Returns

Prompt<any>

onPrompt((session: Session, next: Function) => void)

Registers a handler that will be called every time the prompt is about to send a message to the user. You can use this hook to implement your own custom prompt sending logic. Multiple handlers can be registered and calling next() will invoke the next handler in the chain. The final handler performs the prompts default logic which is to create a new message using formatMessage() and then send it.

function onPrompt(handler: (session: Session, next: Function) => void)

Parameters

handler

(session: Session, next: Function) => void

Function that will be called anytime sendPrompt() is called.

Returns

Prompt<any>

onRecognize((context: IRecognizeDialogContext, callback: (err: Error, score: number, response?: any) => void) => void)

Registers a handler that will be called everytime the prompt receives a reply from the user. The handlers callback() can be used to return a confidence score that it understood the users input as well as the value that should be returned to the caller of the prompt. Calling callback(null, 1.0, true); would indicate a high confidence that the user answered the prompt and would return a boolean true as the response from the prompt. Any response type is possible, including objects. Calling callback(null, 0.0); indicates that the users input was not understood at all and that they should be re-prompted.

Multiple handlers can be registered and unlike the other handler types, all of the registered will be called and handler providing the highest confidence score will be chosen as the winner. When customizing one of the built-in prompt types you'll often want to disable the prompts default recognizer logic. This can be achieved by setting the features of the prompt when you create it. Just keep in mind that if you completely disable the prompts default recognizer logic, you'll need to do all of the recognition yourself.

function onRecognize(handler: (context: IRecognizeDialogContext, callback: (err: Error, score: number, response?: any) => void) => void)

Parameters

handler

(context: IRecognizeDialogContext, callback: (err: Error, score: number, response?: any) => void) => void

Function that will be called to recognize the users reply to a prompt.

Returns

Prompt<any>

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 Prompt which will be run everytime the user replies to the prompt.

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.

msg
TextOrMessageType

(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().

sendPrompt(Session)

Sends a prompt to the user for the current turn. This can be called from a [matches()][#matches] handler to manually send a prompt/reprompt to the user. To force sending of the initial prompt you would need to set session.dialogData.turns = 0; before calling sendPrompt().

function sendPrompt(session: Session)

Parameters

session
Session

Session object for the current conversation.

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.

Returns