Options
All
  • Public
  • Public/Protected
  • All
Menu

A library of related dialogs used for routing purposes. Libraries can be chained together to enable the development of complex bots. The UniversalBot class is itself a Library that forms the root of this chain.

Libraries of reusable parts can be developed by creating a new Library instance and adding dialogs just as you would to a bot. Your library should have a unique name that corresponds to either your libraries website or NPM module name. Bots can then reuse your library by simply adding your parts Library instance to their bot using UniversalBot.library(). If your library itself depends on other libraries you should add them to your library as a dependency using Library.library(). You can easily manage multiple versions of your library by adding a version number to your library name.

To invoke dialogs within your library bots will need to call session.beginDialog() with a fully qualified dialog id in the form of ':'. You'll typically hide this from the devloper by exposing a function from their module that starts the dialog for them. So calling something like myLib.someDialog(session, { arg: '' }); would end up calling session.beginDialog('myLib:someDialog', args); under the covers.

Its worth noting that dialogs are always invoked within the current dialog so once your within a dialog from your library you don't need to prefix every beginDialog() call your with your libraries name. Its only when crossing from one library context to another that you need to include the library name prefix.

Hierarchy

  • Library

Index

Constructors

constructor

  • new Library(name: string): Library
  • Creates a new instance of the library.

    Parameters

    • name: string

      Unique namespace for the library.

    Returns Library

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

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

    Parameters

    • Optional copyTo: Library

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

customAction

  • Registers a custom global action that will call the passed in onSelectAction handler when triggered.

    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 Library

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

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[]

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

onFindRoutes

onSelectRoute

recognize

  • Attempts to match a users text utterance to an intent using the libraries recognizers. See IIntentRecognizer.recognize() for details.

    Parameters

    • context: IRecognizeContext

      Read-only recognizer context for the current conversation.

    • callback: function

      Function that should be invoked upon completion of the recognition.

    Returns void

recognizer

selectActiveDialogRoute

selectGlobalActionRoute

selectRoute

selectStackActionRoute

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