Options
All
  • Public
  • Public/Protected
  • All
Menu

Manages the bots conversation with a user.

Hierarchy

  • Session

Index

Constructors

constructor

Properties

connector

connector: IConnector

The connector being used for this session.

conversationData

conversationData: any

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

dialogData

dialogData: any

Data that's only visible to the current dialog.

library

library: Library

The bots root library of dialogs.

localizer

localizer: ILocalizer

The localizer for the current session.

message

message: IMessage

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

privateConversationData

privateConversationData: any

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

sessionState

sessionState: ISessionState

Sessions current state information.

userData

userData: any

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

Methods

beginDialog

  • beginDialog<T>(id: string, args?: T): Session
  • 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.

    Type parameters

    • T

    Parameters

    • id: string

      Unique ID of the dialog to start.

    • Optional args: T

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

    Returns Session

cancelDialog

  • cancelDialog(dialogId: string | number, replaceWithId?: string, replaceWithArgs?: any): Session
  • 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.

    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.
    • Optional replaceWithId: string

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

    • Optional replaceWithArgs: any

      (Optional) arguments to pass to the new dialog.

    Returns Session

clearDialogStack

delay

  • Inserts a delay between outgoing messages.

    Parameters

    • delay: number

      Number of milliseconds to pause for.

    Returns Session

dialogStack

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

    Parameters

    • Optional 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

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

    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

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

    Parameters

    • Optional message: TextOrMessageType

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

    • Rest ...args: any[]

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

    Returns Session

endDialog

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

    Parameters

    • Optional message: TextOrMessageType

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

    • Rest ...args: any[]

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

    Returns Session

endDialogWithResult

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

    Parameters

    • Optional 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

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

    example
    
    bot.dialog('taskDialog', function (session) {
         try {
              // ... do something that could raise an error ...
         } catch (err) {
              session.error(err);
         }
    });
    

    Parameters

    • err: Error

      Error that occured.

    Returns Session

gettext

  • gettext(msgid: string, ...args: any[]): string
  • 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.)

    example
    
    var msg = session.gettext("")
    

    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.

    • Rest ...args: any[]

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

    Returns string

isReset

  • isReset(): boolean

messageSent

  • messageSent(): boolean
  • Returns true if a message has been sent for this session.

    Returns boolean

ngettext

  • ngettext(msgid: string, msgid_plural: string, count: number): string
  • 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.

    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

  • on(event: string, listener: function): void
  • Registers an event listener.

    Parameters

    • event: string

      Name of the event. Event types:

      • error: An error occured. Passes a JavaScript Error object.
    • listener: function

      Function to invoke.

        • (data: any): void
        • Parameters

          • data: any

            The data for the event. Consult the list above for specific types of data you can expect to receive.

          Returns void

    Returns void

preferredLocale

  • preferredLocale(locale?: string, callback?: function): string
  • Returns the preferred locale when no parameters are supplied, otherwise sets the preferred locale.

    example
    
    bot.dialog('localePicker', [
         function (session) {
              var choices = [
                   { value: 'en', title: "English" },
                   { value: 'es', title: "EspaƱol" }
              ];
              builder.Prompts.choice(session, "Please select your preferred language.", choices);
         },
         function (session, results) {
              var locale = results.response.entity;
              session.preferredLocale(locale);
              session.send("Language updated.").endDialog();
         }
    ]);
    

    Parameters

    • Optional locale: string

      (Optional) the locale to use for localizing messages.

    • Optional callback: function

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

        • (err: Error): void
        • Parameters

          • err: Error

          Returns void

    Returns string

replaceDialog

  • replaceDialog<T>(id: string, args?: T): Session
  • Ends the current dialog and starts a new one its place. The parent dialog will not be resumed until the new dialog completes.

    Type parameters

    • T

    Parameters

    • id: string

      Unique ID of the dialog to start.

    • Optional args: T

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

    Returns Session

reset

  • reset(dialogId?: string, dialogArgs?: any): Session
  • Clears the sessions callstack and restarts the conversation with the configured dialogId.

    Parameters

    • Optional dialogId: string

      (Optional) ID of the dialog to start.

    • Optional dialogArgs: any

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

    Returns Session

routeToActiveDialog

save

say

sayLocalized

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

    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.

    • Optional speak: TextType

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

    • Optional options: IMessageOptions

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

    Returns Session

send

  • Sends a message to the user.

    Parameters

    • message: TextOrMessageType

      Text/message to send to user.

    • Rest ...args: any[]

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

    Returns Session

sendBatch

  • sendBatch(done?: function): void
  • Immediately ends the current batch and delivers any queued up messages.

    Parameters

    • Optional done: function

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

        • (err: Error, addresses?: IAddress[]): void
        • Parameters

          • err: Error

            Any error that occured during the send.

          • Optional addresses: IAddress[]

            An array of address objects returned for each individual message within the batch. These address objects contain the ID of the posted messages so can be used to update or delete a message in the future.

          Returns void

    Returns void

sendLocalized

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

    Parameters

    • libraryNamespace: string

      Namespace to use for localizing the message.

    • message: TextOrMessageType

      Text/message to send to user.

    • Rest ...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.

    Returns Session

toRecognizeContext

watch

  • watch(variable: string, enable?: boolean): Session
  • Enables/disables a watch for the current session.

    Parameters

    • variable: string

      Name of the variable to watch/unwatch.

    • Optional enable: boolean

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

    Returns Session

watchList

  • watchList(): string[]
  • Returns the current list of watched variables for the session.

    Returns string[]

Static activeDialogStackEntry

Static findDialogStackEntry

  • findDialogStackEntry(stack: IDialogState[], dialogId: string, reverse?: boolean): number
  • Searches a dialog stack for a specific dialog, in either a forward or reverse direction, returning its index.

    Parameters

    • stack: IDialogState[]

      The dialog stack to search.

    • dialogId: string

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

    • Optional 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

Static forEachDialogStackEntry

  • forEachDialogStackEntry(stack: IDialogState[], reverse: boolean, fn: function): void
  • Enumerates all a stacks dialog entries in either a forward or reverse direction.

    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: function

      Function to invoke with each entry on the stack.

        • Parameters

          • entry: IDialogState

            The dialog stack entry.

          • index: number

            The index of the dialog within the stack.

          Returns void

    Returns void

Static popDialogStackEntry

Static pruneDialogStack

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

    Parameters

    • stack: IDialogState[]

      The dialog stack to update.

    • start: number

      Index of the first element to remove.

    Returns IDialogState

Static pushDialogStackEntry

Static validateDialogStack

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

    Parameters

    • stack: IDialogState[]

      The dialog stack to validate.

    • root: Library

      The root of the library hierarchy, typically the bot.

    Returns boolean

Static watchable

  • Adds or retrieves a variable that can be watched.

    Parameters

    • variable: string

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

    • Optional 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

Static watchableList

  • watchableList(): string[]

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method