Options
All
  • Public
  • Public/Protected
  • All
Menu

Class UniversalBot

Manages your bots conversations with users across multiple channels.

Hierarchy

Index

Constructors

constructor

  • Creates a new instance of the UniversalBot.

    Parameters

    • Optional connector: IConnector

      (Optional) the default connector to use for requests. If there's not a more specific connector registered for a channel then this connector will be used./**

    • Optional defaultDialog: IDialogWaterfallStep | IDialogWaterfallStep[]

      (Optional) default handler of received messages. This can either be an individual function or a waterfall sequence.

    • Optional libraryName: string

      (Optional) library namespace for the bot. The default value is '*'.

    Returns UniversalBot

Properties

name

name: string

The libraries unique namespace. This is used to issolate the libraries dialogs and localized prompts.

Static RouteTypes

RouteTypes: object

Supported routeType values returned by default from findRoutes().

Type declaration

  • ActiveDialog: string

    The route is for the active dialog on the stack.

  • GlobalAction: string

    The route is for one of the libraries global actions that has been triggered.

  • StackAction: string

    The route is for an action on the dialog stack that has been triggered.

Methods

beginDialog

  • beginDialog(address: IAddress, dialogId: string, dialogArgs?: any, done?: function): void
  • Proactively starts a new dialog with the user. Any current conversation between the bot and user will be replaced with a new dialog stack.

    Parameters

    • address: IAddress

      Address of the user to start a new conversation with. This should be saved during a previous conversation with the user. Any existing conversation or dialog will be immediately terminated.

    • dialogId: string

      ID of the dialog to begin.

    • Optional dialogArgs: any

      (Optional) arguments to pass to dialog.

    • Optional done: function

      (Optional) function to invoke once the operation is completed.

        • (err: Error): void
        • Parameters

          • err: Error

          Returns void

    Returns void

beginDialogAction

  • Registers a global action that will start another dialog anytime its triggered. The new dialog will be pushed onto the stack so it does not automatically end any 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.

    Parameters

    • name: string

      Unique name to assign the action.

    • id: string

      ID of the dialog to start.

    • Optional options: IDialogActionOptions

      (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 Dialog

clone

  • Returns a clone of an existing bot.

    Parameters

    • Optional copyTo: UniversalBot

      (Optional) instance to copy the current object to. If missing a new instance will be created.

    • Optional newName: string

      (Optional) if specified the returned copy will be renamed to a new name.

    Returns UniversalBot

connector

  • Registers or returns a connector for a specific channel.

    Parameters

    • channelId: string

      Unique ID of the channel. Use a channelId of '*' to reference the default connector.

    • Optional connector: IConnector

      (Optional) connector to register. If ommited the connector for channelId will be returned.

    Returns IConnector

customAction

dialog

  • Registers or returns a dialog from the library.

    Parameters

    • id: string

      Unique ID of the dialog being regsitered or retrieved.

    • Optional dialog: Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep

      (Optional) dialog or waterfall to register.

      • dialog: {Dialog} - Dialog to add.
      • dialog: {IDialogWaterfallStep[]} - Waterfall of steps to execute. See IDialogWaterfallStep for details.
      • dialog: {IDialogWaterfallStep} - Single step waterfall. Calling a built-in prompt or starting a new dialog will result in the current dialog ending upon completion of the child prompt/dialog.
    • Optional replace: boolean

      (Optional) if true, the dialog should replace the existing dialog if already registered.

    Returns Dialog

endConversationAction

  • Registers a global action that will end the conversation with the user when triggered.

    Parameters

    • name: string

      Unique name to assign the action.

    • Optional msg: TextOrMessageType

      (Optional) message to send the user prior to ending the conversation.

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

findActiveDialogRoutes

  • Gets the active dialogs confidence that it understands the current message. The dialog must be a member of the current library, otherwise a score of 0.0 will be returned.

    Parameters

    • context: IRecognizeContext

      Read-only recognizer context for the current conversation.

    • callback: function

      Function that should be invoked with the found routes.

        • Parameters

          • err: Error

            Any error that occured during the operation.

          • routes: IRouteResult[]

            List of routes best suited to handle the current message.

          Returns void

    • Optional dialogStack: IDialogState[]

      (Optional) dialog stack to search over. The default behaviour is to search over the sessions current dialog stack.

    Returns void

findDialog

  • findDialog(libName: string, dialogId: string): Dialog
  • Searches the library and all of its dependencies for a specific dialog. Returns the dialog if found, otherwise null.

    Parameters

    • libName: string

      Name of the library containing the dialog.

    • dialogId: string

      Unique ID of the dialog within the library.

    Returns Dialog

findGlobalActionRoutes

  • Searches the library to see if any global actions have been triggered.

    Parameters

    • context: IRecognizeContext

      Read-only recognizer context for the current conversation.

    • callback: function

      Function that should be invoked with the found routes.

        • Parameters

          • err: Error

            Any error that occured during the operation.

          • routes: IRouteResult[]

            List of routes best suited to handle the current message.

          Returns void

    Returns void

findRoutes

  • Searches for candidate routes to handle the current message. To actually initiate the handling of the message you should call selectRoute() with one of the returned results.

    The default search logic can be overriden using onFindRoute() and only the current library is searched so you should call findRoutes() seperately for each library within the hierarchy.

    Parameters

    • context: IRecognizeContext

      Read-only recognizer context for the current conversation.

    • callback: function

      Function that should be invoked with the found routes.

        • Parameters

          • err: Error

            Any error that occured during the operation.

          • routes: IRouteResult[]

            List of routes best suited to handle the current message.

          Returns void

    Returns void

findStackActionRoutes

  • Searches the sessions dialog stack to see if any actions have been triggered.

    Parameters

    • context: IRecognizeContext

      Read-only recognizer context for the current conversation.

    • callback: function

      Function that should be invoked with the found routes.

        • Parameters

          • err: Error

            Any error that occured during the operation.

          • routes: IRouteResult[]

            List of routes best suited to handle the current message.

          Returns void

    • Optional dialogStack: IDialogState[]

      (Optional) dialog stack to search over. The default behaviour is to search over the sessions current dialog stack.

    Returns void

forEachDialog

  • forEachDialog(callback: function): void
  • Enumerates all of the libraries dialogs.

    Parameters

    • callback: function

      Iterator function to call with each dialog.

        • (dialog: Dialog, id: string): void
        • Parameters

          • dialog: Dialog

            The current dialog.

          • id: string

          Returns void

    Returns void

forEachLibrary

  • forEachLibrary(callback: function): void
  • Enumerates all of the libraries child libraries. The caller should take appropriate steps to avoid circular references when enumerating the hierarchy. In most cases calling libraryList() is a better choice as it already contains logic to avoid cycles.

    Parameters

    • callback: function

      Iterator function to call with each child libray.

        • Parameters

          • library: Library

            The current child.

          Returns void

    Returns void

get

  • get(name: string): any

isInConversation

  • isInConversation(address: IAddress, callback: function): void
  • Returns information about when the last turn between the user and a bot occured. This can be called before beginDialog to determine if the user is currently in a conversation with the bot.

    Parameters

    • address: IAddress

      Address of the user to lookup. This should be saved during a previous conversation with the user.

    • callback: function

      Function to invoke with the results of the query.

        • (err: Error, lastAccess: Date): void
        • Parameters

          • err: Error
          • lastAccess: Date

          Returns void

    Returns void

library

  • Registers or returns a library dependency.

    Parameters

    • lib: Library | string
      • lib: {Library} - Library to register as a dependency.
      • lib: {string} - Unique name of the library to lookup. All dependencies will be searched as well.

    Returns Library

libraryList

  • libraryList(reverse?: boolean): Library[]
  • Returns a list of unique libraries within the hierarchy. Should be called on the root of the library hierarchy and avoids cycles created when two child libraries reference the same dependent library.

    Parameters

    • Optional reverse: boolean

      (Optional) If true list will be generated from the leaves up meaning the root library will be listed last. The default value is false which means it will be generated from the roots down and the root library will be listed first.

    Returns Library[]

loadSession

  • loadSession(address: IAddress, callback: function): void
  • Loads a session object for an arbitrary address.

    Parameters

    • address: IAddress

      Address of the user/session to load. This should be saved during a previous conversation with the user.

    • callback: function

      Function to invoke with the loaded session.

        • (err: Error, session: Session): void
        • Parameters

          Returns void

    Returns void

localePath

  • localePath(path?: string): string
  • Gets or sets the path to the libraries "/locale/" folder containing its localized prompts. The prompts for the library should be stored in a "/locale//.json" file under this path where "" representes the 2-3 digit language tage for the locale and "" is a filename matching the libraries namespace.

    Parameters

    • Optional path: string

      (Optional) path to the libraries "/locale/" folder. If specified this will update the libraries path.

    Returns string

on

  • on(event: string, listener: function): void
  • Registers an event listener. The bot will emit its own events as it process incoming and outgoing messages. It will also forward activity related events emitted from the connector, giving you one place to listen for all activity from your bot. The flow of events from the bot is as follows:

    Message Received

    When the bot receives a new message it will emit the following events in order:

    lookupUser -> receive -> incoming -> getStorageData -> routing

    Any receive middleware that's been installed will be executed between the 'receive' and 'incoming' events. After the 'routing' event is emmited any botbuilder middleware will be executed prior to dispatching the message to the bots active dialog.

    Connector Activity Received

    Connectors can emit activity events to signal things like a user is typing or that they friended a bot. These activities get routed through middleware like messages but they are not routed through the bots dialog system. They are only ever emitted as events.

    The flow of connector events is:

    lookupUser -> receive -> (activity)

    Message sent

    Bots can send multiple messages so the session will batch up all outgoing message and then save the bots current state before delivering the sent messages. You'll see a single 'saveStorageData' event emitted and then for every outgoing message in the batch you'll see the following sequence of events:

    send -> outgoing

    Any send middleware that's been installed will be executed between the 'send' and 'outgoing' events.

    Parameters

    • event: string

      Name of the event. Bot and connector specific event types:

      Bot Events

      • error: An error occured. Passed a JavaScript Error object.
      • lookupUser: The user is for an address is about to be looked up. Passed an IAddress object.
      • receive: An incoming message has been received. Passed an IEvent object.
      • incoming: An incoming message has been received and processed by middleware. Passed an IMessage object.
      • routing: An incoming message has been bound to a session and is about to be routed through any session middleware and then dispatched to the active dialog for processing. Passed a Session object.
      • send: An outgoing message is about to be sent to middleware for processing. Passed an IMessage object.
      • outgoing: An outgoing message has just been sent through middleware and is about to be delivered to the users chat client.
      • getStorageData: The sessions persisted state data is being loaded from storage. Passed an IBotStorageContext object.
      • saveStorageData: The sessions persisted state data is being written to storage. Passed an IBotStorageContext object.

      ChatConnector Events

      • conversationUpdate: Your bot was added to a conversation or other conversation metadata changed. Passed an IConversationUpdate object.
      • contactRelationUpdate: The bot was added to or removed from a user's contact list. Passed an IContactRelationUpdate object.
      • typing: The user or bot on the other end of the conversation is typing. Passed an IEvent 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

onDisambiguateRoute

  • Replaces the bots default route disambiguation logic with a custom implementation.

    Parameters

    • handler: IDisambiguateRouteHandler

      Function that will be invoked with the candidate routes to dispatch an incoming message to.

    Returns void

onFindRoutes

onSelectRoute

receive

  • Called when a new event is received. This can be called manually to mimic the bot receiving a message from the user.

    Parameters

    • events: IEvent | IEvent[]

      Event or (array of events) received.

    • Optional done: function

      (Optional) function to invoke once the operation is completed.

        • (err: Error): void
        • Parameters

          • err: Error

          Returns void

    Returns void

recognize

recognizer

selectActiveDialogRoute

selectGlobalActionRoute

selectRoute

selectStackActionRoute

send

  • Sends a message to the user without disrupting the current conversations dialog stack.

    Parameters

    • messages: IIsMessage | IMessage | IMessage[]

      The message (or array of messages) to send the user.

    • Optional done: function

      (Optional) function to invoke once the operation is completed.

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

set

use

  • Installs middleware for the bot. Middleware lets you intercept incoming and outgoing events/messages.

    Parameters

    • Rest ...args: IMiddlewareMap[]

      One or more sets of middleware hooks to install.

    Returns UniversalBot

Static addRouteResult

  • Helper method called from the various route finding methods to manage adding a candidate route to the result set.

    • If the score is greater then the current best match in the set a new result set will be returned containing just the new match.
    • If the score is equal to the current best match it will be added to the existing set.
    • If the score is less than the current best match it will be ignored.

    Parameters

    • route: IRouteResult

      The candidate route to add to the set.

    • Optional current: IRouteResult[]

      (Optional) result set to add the route too. If missing then a new set with just the route will be returned.

    Returns IRouteResult[]

Static bestRouteResult

  • Finds the best route to use within a result set containing multiple ambiguous routes. The following disambigution strategy will be used:

    1. : Custom route types are the highest priority and will alwsays be preferred. This lets the developer override routing within a bot in very powerful way.
    2. ActiveDialog: The active dialog is the next highest priority.
    3. StackAction: Stack actions are the next highest priority and the action with the deepest stack position will be returned.
    4. GlobalAction: Global actions are the lowest priority. If a dialogStack is past in the actions from the library deepest on the stack will be favored. Otherwise the first one will be returned.

    Parameters

    • routes: IRouteResult[]

      Array of candidate routes to filter.

    • Optional dialogStack: IDialogState[]

      (Optional) dialog stack used to determine which libraries global actions to favor.

    • Optional rootLibraryName: string

      (Optional) library namespace to prefer when disambiguating global actions and there's no dialogs on the stack.

    Returns IRouteResult

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