Session class

Reference

Package:: botbuilder

Manages the bots conversation with a user.

Constructors

Creates an instance of the session.

Properties

connector	The connector being used for this session.
conversationData	Shared conversation data that's visible to all members of the conversation.
dialogData	Data that's only visible to the current dialog.
library	The bots root library of dialogs.
localizer	The localizer for the current session.
message	The message received from the user. For bot originated messages this may only contain the "to" & "from" fields.
privateConversationData	Private conversation data that's only visible to the user.
sessionState	Sessions current state information.
userData	Data for the user that's persisted across all conversations with the bot.

Methods

activeDialogStackEntry(IDialogState[])	Returns a stacks active dialog or null.
beginDialog<T>(string, T)	Passes control of the conversation to a new dialog. The current dialog will be suspended until the child dialog completes. Once the child ends the current dialog will receive a call to dialogResumed() where it can inspect any results returned from the child.
cancelDialog(string \| number, string, any)	Cancels an existing dialog and optionally starts a new one it its place. Unlike endDialog() and replaceDialog() which affect the current dialog, this method lets you end a parent dialog anywhere on the stack. The parent of the canceled dialog will be continued as if the dialog had called endDialog(). A special ResumeReason.canceled will be returned to indicate that the dialog was canceled.
clearDialogStack()	Clears the current dialog stack.
delay(number)	Inserts a delay between outgoing messages.
dialogStack(IDialogState[])	Gets/sets the current dialog stack. A copy of the current dialog is returned so if any changes are made to the returned stack they will need to be copied back to the session via a second call to `session.dialogStack()`.
dispatch(ISessionState, IMessage, Function)	Finalizes the initialization of the session object and then routes the session through all installed middleware. The passed in `next()` function will be called as the last step of the middleware chain.
endConversation(TextOrMessageType, any[])	Ends the current conversation and optionally sends a message to the user.
endDialog(TextOrMessageType, any[])	Ends the current dialog and optionally sends a message to the user. The parent will be resumed with an IDialogResult.resumed reason of completed.
endDialogWithResult(IDialogResult<any>)	Ends the current dialog and optionally returns a result to the dialogs parent.
error(Error)	Signals that an error occured. The bot will signal the error via an on('error', err) event.
findDialogStackEntry(IDialogState[], string, boolean)	Searches a dialog stack for a specific dialog, in either a forward or reverse direction, returning its index.
forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)	Enumerates all a stacks dialog entries in either a forward or reverse direction.
gettext(string, any[])	Loads a localized string for the messages language. If arguments are passed the localized string will be treated as a template and formatted using sprintf-js (see their docs for details.)
isReset()	Returns true if the session has been reset.
messageSent()	Returns true if a message has been sent for this session.
ngettext(string, string, number)	Loads the plural form of a localized string for the messages language. The output string will be formatted to include the count by replacing %d in the string with the count.
on(string, (data: any) => void)	Registers an event listener.
popDialogStackEntry(IDialogState[])	Pops the active dialog off a stack and returns the new one if the stack isn't empty.
preferredLocale(string, (err: Error) => void)	Returns the preferred locale when no parameters are supplied, otherwise sets the preferred locale.
pruneDialogStack(IDialogState[], number)	Deletes all dialog stack entries starting with the specified index and returns the new active dialog.
pushDialogStackEntry(IDialogState[], IDialogState)	Pushes a new dialog onto a stack and returns it as the active dialog.
replaceDialog<T>(string, T)	Ends the current dialog and starts a new one its place. The parent dialog will not be resumed until the new dialog completes.
reset(string, any)	Clears the sessions callstack and restarts the conversation with the configured dialogId.
routeToActiveDialog(IRecognizeResult)	Dispatches the session to either the active dialog or the default dialog for processing.
save()	Triggers saving of changes made to dialogData, userData, conversationdata, or [privateConversationData'(#privateconversationdata).
say(TextType, IMessageOptions)
say(TextType, TextType, IMessageOptions)	Sends a text, and optional SSML, message to the user.
sayLocalized(string, TextType, TextType, IMessageOptions)	Sends a text, and optional SSML, message to the user using a specific localization namespace.
send(TextOrMessageType, any[])	Sends a message to the user.
sendBatch((err: Error, addresses?: IAddress[]) => void)	Immediately ends the current batch and delivers any queued up messages.
sendLocalized(string, TextOrMessageType, any[])	Sends a message to a user using a specific localization namespace.
sendTyping()	Sends the user an indication that the bot is typing. For long running operations this should be called every few seconds.
toRecognizeContext()	Returns the session object as a read only context object.
validateDialogStack(IDialogState[], Library)	Ensures that all of the entries on a dialog stack reference valid dialogs within a library hierarchy.
watch(string, boolean)	Enables/disables a watch for the current session.
watchable(string, IWatchableHandler)	Adds or retrieves a variable that can be watched.
watchableList()	Returns a list of watchable variables.
watchList()	Returns the current list of watched variables for the session.

Constructor Details

Session(ISessionOptions)

Creates an instance of the session.

new Session(options: ISessionOptions)

Parameters

options: ISessionOptions

Sessions configuration options.

Property Details

connector

The connector being used for this session.

connector: IConnector

Property Value

IConnector

conversationData

Shared conversation data that's visible to all members of the conversation.

conversationData: any

Property Value

any

dialogData

Data that's only visible to the current dialog.

dialogData: any

Property Value

any

library

The bots root library of dialogs.

library: Library

Property Value

Library

localizer

The localizer for the current session.

localizer: ILocalizer

Property Value

ILocalizer

message

The message received from the user. For bot originated messages this may only contain the "to" & "from" fields.

message: IMessage

Property Value

IMessage

privateConversationData

Private conversation data that's only visible to the user.

privateConversationData: any

Property Value

any

sessionState

Sessions current state information.

sessionState: ISessionState

Property Value

ISessionState

userData

Data for the user that's persisted across all conversations with the bot.

userData: any

Property Value

any

Method Details

activeDialogStackEntry(IDialogState[])

Returns a stacks active dialog or null.

static function activeDialogStackEntry(stack: IDialogState[])

Parameters

stack: IDialogState[]

The dialog stack to return the entry for.

Returns

IDialogState

beginDialog<T>(string, T)

Passes control of the conversation to a new dialog. The current dialog will be suspended until the child dialog completes. Once the child ends the current dialog will receive a call to dialogResumed() where it can inspect any results returned from the child.

function beginDialog<T>(id: string, args?: T)

Parameters

id: string

Unique ID of the dialog to start.

args: T

(Optional) arguments to pass to the dialogs begin() method.

Returns

Session

cancelDialog(string | number, string, any)

Cancels an existing dialog and optionally starts a new one it its place. Unlike endDialog() and replaceDialog() which affect the current dialog, this method lets you end a parent dialog anywhere on the stack. The parent of the canceled dialog will be continued as if the dialog had called endDialog(). A special ResumeReason.canceled will be returned to indicate that the dialog was canceled.

function cancelDialog(dialogId: string | number, replaceWithId?: string, replaceWithArgs?: any)

Parameters

dialogId: string | number

dialogId: {string} - ID of the dialog to end. If multiple occurences of the dialog exist on the dialog stack, the last occurance will be canceled.
dialogId: {number} - Index of the dialog on the stack to cancel. This is the preferred way to cancel a dialog from an action handler as it ensures that the correct instance is canceled.

replaceWithId: string

(Optional) specifies an ID to start in the canceled dialogs place. This prevents the dialogs parent from being resumed.

replaceWithArgs: any

(Optional) arguments to pass to the new dialog.

Returns

Session

clearDialogStack()

Clears the current dialog stack.

function clearDialogStack()

Returns

Session

delay(number)

Inserts a delay between outgoing messages.

function delay(delay: number)

Parameters

delay: number

Number of milliseconds to pause for.

Returns

Session

dialogStack(IDialogState[])

Gets/sets the current dialog stack. A copy of the current dialog is returned so if any changes are made to the returned stack they will need to be copied back to the session via a second call to session.dialogStack().

function dialogStack(newStack?: IDialogState[])

Parameters

newStack: IDialogState[]

(Optional) dialog stack to assign to session. The sessions dialogData will be updated to reflect the state of the new active dialog.

Returns

IDialogState[]

dispatch(ISessionState, IMessage, Function)

Finalizes the initialization of the session object and then routes the session through all installed middleware. The passed in next() function will be called as the last step of the middleware chain.

function dispatch(sessionState: ISessionState, message: IMessage, next: Function)

Parameters

sessionState: ISessionState

The current session state. If null a new conversation will be started beginning with the configured dialogId.

message: IMessage

The message to route through middleware.

next: Function

The function to invoke as the last step of the middleware chain.

Returns

Session

endConversation(TextOrMessageType, any[])

Ends the current conversation and optionally sends a message to the user.

function endConversation(message?: TextOrMessageType, args: any[])

Parameters

message: TextOrMessageType

(Optional) text/message to send the user before ending the conversation.

args: any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

Session

endDialog(TextOrMessageType, any[])

Ends the current dialog and optionally sends a message to the user. The parent will be resumed with an IDialogResult.resumed reason of completed.

function endDialog(message?: TextOrMessageType, args: any[])

Parameters

message: TextOrMessageType

(Optional) text/message to send the user before ending the dialog.

args: any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

Session

endDialogWithResult(IDialogResult<any>)

Ends the current dialog and optionally returns a result to the dialogs parent.

function endDialogWithResult(result?: IDialogResult<any>)

Parameters

result: IDialogResult<any>

(Optional) result to send the user. The value you'd like to return should be in the response field.

Returns

Session

error(Error)

Signals that an error occured. The bot will signal the error via an on('error', err) event.

function error(err: Error)

Parameters

err: Error

Error that occured.

Returns

Session

findDialogStackEntry(IDialogState[], string, boolean)

Searches a dialog stack for a specific dialog, in either a forward or reverse direction, returning its index.

static function findDialogStackEntry(stack: IDialogState[], dialogId: string, reverse?: boolean)

Parameters

stack: IDialogState[]

The dialog stack to search.

dialogId: string

The unique ID of the dialog, in <namespace>:<dialog> format, to search for.

reverse: boolean

(Optional) if true the stack will be searched starting with the active dialog and working its way up to the root.

Returns

number

forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)

Enumerates all a stacks dialog entries in either a forward or reverse direction.

static function forEachDialogStackEntry(stack: IDialogState[], reverse: boolean, fn: (entry: IDialogState, index: number) => void)

Parameters

stack: IDialogState[]

The dialog stack to enumerate.

reverse: boolean

If true the entries will be enumerated starting with the active dialog and working up to the root dialog.

fn: (entry: IDialogState, index: number) => void

Function to invoke with each entry on the stack.

gettext(string, any[])

Loads a localized string for the messages language. If arguments are passed the localized string will be treated as a template and formatted using sprintf-js (see their docs for details.)

function gettext(msgid: string, args: any[])

Parameters

msgid: string

String to use as a key in the localized string table. Typically this will just be the english version of the string.

args: any[]

(Optional) arguments used to format the final output string.

Returns

string

isReset()

Returns true if the session has been reset.

function isReset()

Returns

boolean

messageSent()

Returns true if a message has been sent for this session.

function messageSent()

Returns

boolean

ngettext(string, string, number)

Loads the plural form of a localized string for the messages language. The output string will be formatted to include the count by replacing %d in the string with the count.

function ngettext(msgid: string, msgid_plural: string, count: number)

Parameters

msgid: string

Singular form of the string to use as a key in the localized string table. Use %d to specify where the count should go.

msgid_plural: string

Plural form of the string to use as a key in the localized string table. Use %d to specify where the count should go.

count: number

Count to use when determining whether the singular or plural form of the string should be used.

Returns

string

on(string, (data: any) => void)

Registers an event listener.

function on(event: string, listener: (data: any) => void)

Parameters

event: string

Name of the event. Event types:

error: An error occured. Passes a JavaScript Error object.

listener: (data: any) => void

Function to invoke.

popDialogStackEntry(IDialogState[])

Pops the active dialog off a stack and returns the new one if the stack isn't empty.

static function popDialogStackEntry(stack: IDialogState[])

Parameters

stack: IDialogState[]

The dialog stack to update.

Returns

IDialogState

preferredLocale(string, (err: Error) => void)

Returns the preferred locale when no parameters are supplied, otherwise sets the preferred locale.

function preferredLocale(locale?: string, callback?: (err: Error) => void)

Parameters

locale: string

(Optional) the locale to use for localizing messages.

callback: (err: Error) => void

(Optional) function called when the localization table has been loaded for the supplied locale.

Returns

string

pruneDialogStack(IDialogState[], number)

Deletes all dialog stack entries starting with the specified index and returns the new active dialog.

static function pruneDialogStack(stack: IDialogState[], start: number)

Parameters

stack: IDialogState[]

The dialog stack to update.

start: number

Index of the first element to remove.

Returns

IDialogState

pushDialogStackEntry(IDialogState[], IDialogState)

Pushes a new dialog onto a stack and returns it as the active dialog.

static function pushDialogStackEntry(stack: IDialogState[], entry: IDialogState)

Parameters

stack: IDialogState[]

The dialog stack to update.

entry: IDialogState

Dialog entry to push onto the stack.

Returns

IDialogState

replaceDialog<T>(string, T)

Ends the current dialog and starts a new one its place. The parent dialog will not be resumed until the new dialog completes.

function replaceDialog<T>(id: string, args?: T)

Parameters

id: string

Unique ID of the dialog to start.

args: T

(Optional) arguments to pass to the dialogs begin() method.

Returns

Session

reset(string, any)

Clears the sessions callstack and restarts the conversation with the configured dialogId.

function reset(dialogId?: string, dialogArgs?: any)

Parameters

dialogId: string

(Optional) ID of the dialog to start.

dialogArgs: any

(Optional) arguments to pass to the dialogs begin() method.

Returns

Session

routeToActiveDialog(IRecognizeResult)

Dispatches the session to either the active dialog or the default dialog for processing.

function routeToActiveDialog(recognizeResult?: IRecognizeResult)

Parameters

recognizeResult: IRecognizeResult

(Optional) results returned from calling Library.findRoutes(), Library.findActiveDialogRoutes(), * or Dialog.recognize().

save()

Triggers saving of changes made to dialogData, userData, conversationdata, or [privateConversationData'(#privateconversationdata).

function save()

Returns

Session

say(TextType, IMessageOptions)

function say(text: TextType, options?: IMessageOptions)

Parameters

text: TextType

options: IMessageOptions

Returns

Session

say(TextType, TextType, IMessageOptions)

Sends a text, and optional SSML, message to the user.

function say(text: TextType, speak?: TextType, options?: IMessageOptions)

Parameters

text: TextType

Text to send to the user. This can be null to send only SSML or attachments.

speak: TextType

(Optional) message that should be spoken to the user. The message should be formatted as Speech Synthesis Markup Language (SSML). If an array is passed a response will be chosen at random.

options: IMessageOptions

(Optional) properties that should be included on the outgoing message.

Returns

Session

sayLocalized(string, TextType, TextType, IMessageOptions)

Sends a text, and optional SSML, message to the user using a specific localization namespace.

function sayLocalized(libraryNamespace: string, text: TextType, speak?: TextType, options?: IMessageOptions)

Parameters

libraryNamespace: string

Namespace to use for localizing the message.

text: TextType

Text to send to the user. This can be null to send only SSML or attachments.

speak: TextType

(Optional) message that should be spoken to the user. The message should be formatted as Speech Synthesis Markup Language (SSML). If an array is passed a response will be chosen at random.

options: IMessageOptions

(Optional) properties that should be included on the outgoing message.

Returns

Session

send(TextOrMessageType, any[])

Sends a message to the user.

function send(message: TextOrMessageType, args: any[])

Parameters

message: TextOrMessageType

Text/message to send to user. If an array is passed a response will be chosen at random.

args: any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

Session

sendBatch((err: Error, addresses?: IAddress[]) => void)

Immediately ends the current batch and delivers any queued up messages.

function sendBatch(done?: (err: Error, addresses?: IAddress[]) => void)

Parameters

done: (err: Error, addresses?: IAddress[]) => void

(Optional) function called when the batch was either successfully delievered or failed for some reason.

sendLocalized(string, TextOrMessageType, any[])

Sends a message to a user using a specific localization namespace.

function sendLocalized(libraryNamespace: string, message: TextOrMessageType, args: any[])

Parameters

libraryNamespace: string

Namespace to use for localizing the message.

message: TextOrMessageType

Text/message to send to user.

args: any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

Session

sendTyping()

Sends the user an indication that the bot is typing. For long running operations this should be called every few seconds.

function sendTyping()

Returns

Session

toRecognizeContext()

Returns the session object as a read only context object.

function toRecognizeContext()

Returns

IRecognizeContext

validateDialogStack(IDialogState[], Library)

Ensures that all of the entries on a dialog stack reference valid dialogs within a library hierarchy.

static function validateDialogStack(stack: IDialogState[], root: Library)

Parameters

stack: IDialogState[]

The dialog stack to validate.

root: Library

The root of the library hierarchy, typically the bot.

Returns

boolean

watch(string, boolean)

Enables/disables a watch for the current session.

function watch(variable: string, enable?: boolean)

Parameters

variable: string

Name of the variable to watch/unwatch.

enable: boolean

(Optional) If true the variable will be watched, otherwise it will be unwatched. The default value is true.

Returns

Session

watchable(string, IWatchableHandler)

Adds or retrieves a variable that can be watched.

static function watchable(variable: string, handler?: IWatchableHandler)

Parameters

variable: string

Name of the variable that can be watched. Case is used for display only.

handler: IWatchableHandler

(Optional) Function used to retrieve the variables current value. If specified a new handler will be registered, otherwise the existing handler will be retrieved.

Returns

IWatchableHandler

watchableList()

Returns a list of watchable variables.

static function watchableList()

Returns

string[]

watchList()

Returns the current list of watched variables for the session.

function watchList()

Returns

string[]