botbuilder package

Classes

ActionSet

Implement support for named actions which can be bound to a dialog to handle global utterances from the user like "help" or "cancel". Actions get pushed onto and off of the dialog stack as part of dialogs so these listeners can come into and out of scope as the conversation progresses. You can also bind named to actions to buttons which let your bot respond to button clicks on cards that have maybe scrolled off the screen.

AnimationCard

Card builder class that simplifies building Animation cards.

AudioCard

Card builder class that simplifies building Media cards.

BotConnectorBot

DEPRECATED use UniversalBot and a ChatConnector instead.

CardAction

Builder class to simplify adding actions to a card.

CardImage

Builder class to simplify adding images to a card.

CardMedia

Definition of a media entity for a card

ChatConnector

Connects a UniversalBot to multiple channels via the Bot Framework.

CommandDialog

DEPRECATED use an IntentDialog instead.

ConsoleConnector

Connects a UniversalBot to the command line via a console window.

Dialog

Base class for all dialogs. Dialogs are the core component of the BotBuilder framework. Bots use Dialogs to manage arbitrarily complex conversations with a user.

DialogAction

Dialog actions offer static shortcuts to implementing common actions. They also implement support for named actions which can be bound to a dialog to handle global utterances from the user like "help" or "cancel". Actions get pushed onto and off of the dialog stack as part of dialogs so these listeners can come into and out of scope as the conversation progresses. You can also bind named to actions to buttons which let your bot respond to button clicks on cards that have maybe scrolled off the screen.

EntityRecognizer

Utility class used to parse & resolve common entities like datetimes received from LUIS.

Fact

Builder class to simplify creating a list of facts for a card like a receipt.

HeroCard

Card builder class that simplifies building hero cards. Hero cards contain the same information as a thumbnail card, just with a larger more pronounced layout for the cards images.

IntentDialog

Identifies a users intent and optionally extracts entities from a users utterance.

IntentRecognizer

Base class for all core recognizers. Allows conditional execution of a recognizer and post filtering of recognized intents. Derived class should override the abstract onRecognize() method.

IntentRecognizerSet

Federates a recognize() call across a set of intent recognizers.

Keyboard

Card builder class that simplifies building keyboard cards.

Library

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

It's 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. It's only when crossing from one library context to another that you need to include the library name prefix.

LocalizedRegExpRecognizer

Version of the RegExpRecognizer that uses the frameworks localization system to retrieve a localized regular expression. The lookup key in the index.json file should be provided and upon receiving a message for a new locale, the recognizer will retrieve the localized expression and a new case insensitive RegExp will be created and used to recognize the intent. Libraries can use this feature to let a bot override their default matching expressions. just create instances of the recognizer using the namespace of your library and bot developers can customize your matching expressions by using a <namespace>.json file in their locale directory.

LuisDialog

DEPRECATED use an IntentDialog with a LuisRecognizer instead.

LuisRecognizer

Intent recognizer plugin that detects a users intent using Microsofts Language Understanding Intelligent Service (LUIS) The service URLs for multiple LUIS models (apps) can be passed in to support recognition across multiple languages.

MediaCard

Card builder class that simplifies building Media cards.

MemoryBotStorage

Default in memory storage implementation for storing user & session state data.

Message

Message builder class that simplifies building complex messages with attachments.

Middleware
OAuthCard

Card builder class that simplifies building oauth cards.

Prompt

Base class for built-in prompts and can be used to build new custom prompts. The Prompt class provides the basic logic to prompt/re-prompt a user and provides a set of extensible hooks to customize the prompts recognition of the users reply as well as the output sent to the user. Prompts should always have at least one onRecognize() handler registered and they support adding any number of matches() or matchesAny() handlers which can be used to add special user initiated commands to the prompt. For instance, the built-in prompts add a matches('BotBuilder.RepeatIntent') to listen for a user to ask to have a prompt repeated, causing the prompt to send its initial prompt again.

PromptAttachment

Customizable attachment prompt.

PromptChoice

Customizable choice prompt.

PromptConfirm

Customizable confirmation prompt.

PromptNumber

Customizable confirmation prompt.

PromptText

Customizable text prompt.

PromptTime

Customizable time prompt.

ReceiptCard

Card builder class that simplifies building receipt cards.

ReceiptItem

Builder class to simplify adding items to a receipt card.

RegExpRecognizer

Intent recognizer plugin that detects a users intent using a regular expression. Multiple expressions can be passed in to support recognizing across multiple languages.

RemoteSessionLogger

Logs session activity to a remote endpoint using debug events. The remote debugger is automatically used when the emulator connects to your bot. Non-emulator channels can stream their activity to the emulator by saving the address of the emulator session to session.privateConversationData["BotBuilder.Data.DebugSession"].

Session

Manages the bots conversation with a user.

SessionLogger

Default session logger used to log session activity to the console.

SigninCard

Card builder class that simplifies building signin cards.

SimpleDialog

Allows for the creation of custom dialogs that are based on a simple closure. This is useful for cases where you want a dynamic conversation flow or you have a situation that just doesn’t map very well to using a waterfall. The things to keep in mind:

  • Your dialogs closure is can get called in two different contexts that you potentially need to test for. It will get called as expected when the user send your dialog a message but if you call another prompt or dialog from your closure it will get called a second time with the results from the prompt/dialog. You can typically test for this second case by checking for the existant of an args.resumed property. It's important to avoid getting yourself into an infinite loop which can be easy to do.
  • Unlike a waterfall your dialog will not automatically end. It will remain the active dialog until you call session.endDialog().
SimplePromptRecognizer

DEPRECATED no longer supported as of v3.8. Use custom prompts instead.

SuggestedActions

Builder class to add suggested actions to a message

TextBot

DEPRECATED use UniversalBot and a ConsoleConnector instead.

ThumbnailCard

Card builder class that simplifies building thumbnail cards.

UniversalBot

Manages your bots conversations with users across multiple channels.

VideoCard

Card builder class that simplifies building Video cards.

WaterfallDialog

Allows for the creation of custom dialogs that are based on a waterfall.

Interfaces

IActionRouteData

Arguments passed to a triggered action.

IAddress

Address routing information for an event. Addresses are bidirectional meaning they can be used to address both incoming and outgoing events. They're also connector specific meaning that connectors are free to add their own fields to the address. To send a proactive message to a user bots should save the address from a received message. Depending on the channel addresses can change, so bots should periodically update the address stored for a given user.

IAnimationCard

Interface definition for an animation card

IAttachment

Many messaging channels provide the ability to attach richer objects. Bot Builder lets you express these attachments in a cross channel way and connectors will do their best to render the attachments using the channels native constructs. If you desire more control over the channels rendering of a message you can use IEvent.sourceEvent to provide attachments using the channels native schema. The types of attachments that can be sent varies by channel but these are the basic types:

  • Media and Files: Basic files can be sent by setting contentType to the MIME type of the file and then passing a link to the file in contentUrl.
  • Cards: A rich set of visual cards can by setting contentType to the cards type and then passing the JSON for the card in content. If you use one of the rich card builder classes like HeroCard the attachment will automatically filled in for you.
IAudioCard

Interface definition for an audio card

IBeginDialogActionOptions

Options passed when defining a beginDialogAction().

IBotStateData

Exported bot state data.

IBotStateDataResult

Result object returned from ChatConnector.exportBotStateData().

IBotStorage

Replaceable storage system used by UniversalBot.

IBotStorageContext

Context object passed to IBotStorage calls.

IBotStorageData

Data values persisted to IBotStorage.

ICancelActionOptions

Options passed when defining a cancelAction().

ICardAction

The action that should be performed when a card, button, or image is tapped.

ICardImage

An image on a card.

ICardMediaUrl

Url information describing media for a card

IChatConnectorAddress

ChatConnector specific address.

IChatConnectorEndpoint

Options used to set various endpoints in a ChatConnector instance. This should not be changed and is normally not provided by developers in IChatConnectorSettings. Instead the two properties in IChatConnectorSettings, "stateEndpoint," and "openIdMetadata" should be changed there.

IChatConnectorSettings

Options used to initialize a ChatConnector instance.

IChoice

A choice that can be passed to Prompts.choice() or [PromptRecognizers.recognizeChoices()][/en-us/node/builder/chat-reference/classes/botbuilder_d.promptrecognizers#recognizechoices].

IConnector

Implemented by connector plugins for the UniversalBot.

IContactRelationUpdate

A user has updated their contact list. /** A user has updated their contact list.

IConversationMembers

List of members within a conversation.

IConversationUpdate

The Properties of a conversation have changed.

IConversationsResult

Result object returned from ChatConnector.getConversations().

IDefaultLocalizerSettings

Settings used to initialize an ILocalizer implementation.

IDialogActionOptions

Options passed when defining a dialog action.

IDialogResult

Results returned by a child dialog to its parent via a call to session.endDialog().

IDialogState

An entry on the sessions dialog stack.

IDialogVersionOptions

Options passed to Middleware.dialogVersion().

IDialogWaterfallStep

Signature for functions passed as steps to DialogAction.waterfall(). Waterfalls let you prompt a user for information using a sequence of questions. Each step of the waterfall can either execute one of the built-in Prompts, start a new dialog by calling session.beginDialog(), advance to the next step of the waterfall manually using skip(), or terminate the waterfall.

When either a dialog or built-in prompt is called from a waterfall step, the results from that dialog or prompt will be passed via the results parameter to the next step of the waterfall. Users can say things like "never mind" to cancel the built-in prompts so you should guard against that by at least checking for results.response before proceeding. A more detailed explanation of why the waterfall is being continued can be determined by looking at the code returned for results.resumed.

You can manually advance to the next step of the waterfall using the skip() function passed in. Calling skip({ response: "some text" }) with an IDialogResult lets you more accurately mimic the results from a built-in prompt and can simplify your overall waterfall logic.

You can terminate a waterfall early by either falling through every step of the waterfall using calls to skip() or simply not starting another prompt or dialog.

note: Waterfalls have a hidden last step which will automatically end the current dialog if if you call a prompt or dialog from the last step. This is useful where you have a deep stack of dialogs and want a call to session.endDialog() from the last child on the stack to end the entire stack. The close of the last child will trigger all of its parents to move to this hidden step which will cascade the close all the way up the stack. This is typically a desired behavior but if you want to avoid it or stop it somewhere in the middle you'll need to add a step to the end of your waterfall that either does nothing or calls something like session.send() which isn't going to advance the waterfall forward.

IDisambiguateChoices

Route choices to pass to Prompts.disambiguate(). The key for the map should be the localized label to display to the user and the value should be the route to select when chosen by the user. You can pass null for the route to give the user the option to cancel.

IDisambiguateRouteHandler

Custom route disambiguation logic passed to UniversalBot.onDisambiguateRoute().

IEntity

A recognized entity.

IEvent

An event received from or being sent to a source.

IEventMiddleware

Function signature for a piece of middleware that hooks the 'receive' or 'send' events.

IFact

A fact displayed on a card like a receipt.

IFindActionRouteContext

Context passed to ActionSet.findActionRoutes().

IFindMatchResult

Result returned from a call to EntityRecognizer.findBestMatch() or EntityRecognizer.findAllMatches().

IFindRoutesHandler

Custom route searching logic passed to Library.onFindRoutes().

IFirstRunOptions

Options passed to Middleware.firstRun().

IIdentity

Represents a user, bot, or conversation.

IIntent

A recognized intent.

IIntentDialogOptions

Options used to configure an IntentDialog.

IIntentRecognizer

Interface implemented by intent recognizer plugins like the LuisRecognizer class.

IIntentRecognizerResult

Results returned by an intent recognizer.

IIntentRecognizerSetOptions

Options used to configure an IntentRecognizerSet.

IIsAttachment

Implemented by classes that can be converted into an attachment.

IIsCardAction

Implemented by classes that can be converted into a card action.

IIsCardImage

Implemented by classes that can be converted into a card image.

IIsCardMedia

Entities that can be converted to Media for cards

IIsFact

Implemented by classes that can be converted into a fact.

IIsMessage

Implemented by classes that can be converted into an IMessage, like the Message builder class.

IIsReceiptItem

Implemented by classes that can be converted into a receipt item.

IIsSuggestedActions

Implemented by classes that can be converted into suggested actions

ILocalizer

Plugin for localizing messages sent to the user by a bot.

ILuisModelMap

A per/local mapping of LUIS service url's to use for a LuisRecognizer.

IMediaCard

Interface definition of a generic MediaCard, which in its concrete form can be an Audio, Animation or Video card

IMediaEventValue

Supplementary parameter for media events.

IMessage

A chat message sent between a User and a Bot. Messages from the bot to the user come in two flavors:

  • reactive messages are messages sent from the Bot to the User as a reply to an incoming message from the user.
  • proactive messages are messages sent from the Bot to the User in response to some external event like an alarm triggering.

In the reactive case the you should copy the address field from the incoming message to the outgoing message (if you use the Message builder class and initialize it with the session this will happen automatically) and then set the text or attachments. For proactive messages you’ll need save the address from the incoming message to an external storage somewhere. You can then later pass this in to UniversalBot.beginDialog() or copy it to an outgoing message passed to UniversalBot.send().

Composing a message to the user using the incoming address object will by default send a reply to the user in the context of the current conversation. Some channels allow for the starting of new conversations with the user. To start a new proactive conversation with the user simply delete the conversation field from the address object before composing the outgoing message.

IMessageOptions

Optional message properties that can be sent to things like prompts or session.say().

IMessageReaction

Message reaction object.

IMessageUpdate

The Properties of a message have changed.

IMiddlewareMap

Map of middleware hooks that can be registered in a call to UniversalBot.use().

IOAuthCard

An interface representing OAuthCard. A card representing a request to peform a sign in via OAuth

IPagedMembersResult

Result object returned from ChatConnector.getConversationPagedMembers().

IPromptArgs

DEPRECATED the new prompt system just uses IPromptOptions.

IPromptAttachmentFeatures

Optional features for PromptAttachment class.

IPromptAttachmentOptions

Options passed to Prompts.attachment() or in a session.beginDialog() call to a custom prompt based on the PromptAttachment class.

IPromptAttachmentResult

Strongly typed Attachment Prompt Result.

IPromptChoiceFeatures

Optional features for PromptChoice class.

IPromptChoiceOptions

Options passed to Prompts.choice() or in a session.beginDialog() call to a custom prompt based on the PromptChoice class.

IPromptChoiceResult

Strongly typed Choice Prompt Result.

IPromptConfirmResult

Strongly typed Confirm Prompt Result.

IPromptContext

Contextual information tracked for a Prompt. This information can be accessed within a prompt through session.dialogData.

IPromptFeatures

Optional features that should be enabled/disabled when creating a custom Prompt

IPromptNumberOptions

Options passed to Prompts.number() or in a session.beginDialog() call to a custom prompt based on the PromptNumber class.

IPromptNumberResult

Strongly typed Number Prompt Result.

IPromptOptions

Options passed to the built-in prompts.

IPromptRecognizeChoicesOptions

Options passed to PromptRecognizers.recognizeChoices().

IPromptRecognizeNumbersOptions

Options passed to PromptRecognizers.recognizeNumbers().

IPromptRecognizeTimesOptions

Options passed to PromptRecognizers.recognizeTimes().

IPromptRecognizeValuesOptions

Options passed to PromptRecognizers.recognizeValues().

IPromptRecognizer

DEPRECATED no longer supported as of v3.8. Use custom prompts instead.

IPromptRecognizerArgs

DEPRECATED no longer supported as of v3.8. Use custom prompts instead.

IPromptRecognizerResult

Result returned from an IPromptRecognizer.

IPromptResult

Dialog result returned by a system prompt.

IPromptTextFeatures

Optional features for PromptText class.

IPromptTextOptions

Options passed to Prompts.text() or in a session.beginDialog() call to a custom prompt based on the PromptText class.

IPromptTextResult

Strongly typed Text Prompt Result.

IPromptTimeResult

Strongly typed Time Prompt Result.

IPromptsOptions

DEPRECATED no longer supported as of v3.8. Use custom prompts instead.

IReceiptCard

Displays a rich receipt to a user for something they've either bought or are planning to buy.

IReceiptItem

An individual item within a receipt.

IRecognizeContext

Context of the received message passed to various recognition methods.

IRecognizeDialogContext

Context passed to Dialog.recognize().

IRecognizeResult

Results from a call to a recognize() function. The implementation is free to add any additional properties to the result.

IRegExpMap

A per/local mapping of regular expressions to use for a RegExpRecognizer.

IRouteResult

Candidate route returned by Library.findRoutes().

ISelectRouteHandler

Custom route searching logic passed to Library.onSelectRoute().

ISemanticAction

Represents a reference to a programmatic action.

ISessionMiddleware

Function signature for a piece of middleware that hooks the 'botbuilder' event.

ISessionOptions

Options passed to the constructor of a session.

ISessionState

Persisted session state used to track a conversations dialog stack.

ISigninCard

Displays a signin card and button to the user. Some channels may choose to render this as a text prompt and link to click.

ISourceEventMap

A per/source mapping of custom event data to send.

IStartConversationAddress

Additional properties that can be passed in with the address to UniversalBot.beginDialog().

ISuggestedActions

Suggested actions to send to the user and displayed as quick replies. Suggested actions will be displayed only on the channels that support suggested actions.

ITextHighlight

An interface representing TextHighlight. Refers to a substring of content within another field.

IThumbnailCard

Displays a card to the user using either a smaller thumbnail layout or larger hero layout (the attachments contentType determines which). All of the cards fields are optional so this card can be used to specify things like a keyboard on certain channels. Some channels may choose to render a lower fidelity version of the card or use an alternate representation.

ITokenResponse

An interface representing TokenResponse. A response that includes a user token

ITranscript

An interface representing historic activities.

ITriggerActionOptions

Options passed when defining a triggerAction().

IUniversalBotSettings

Options used to initialize a UniversalBot instance.

IVideoCard

Interface definition for a video card

IWatchableHandler

Function for retrieving the value of a watched variable. Passed to Session.watchable().

Type Aliases

AttachmentType

Some methods can take either an IAttachment in JSON form or one the various card builder classes that implement IIsAttachment.

MatchType

Supported rules for matching a users utterance.

  • {RegExp} - A regular expression will be used to match the users utterance.
  • {string} - A named intent returned from a recognizer will be used to match the users utterance.
  • {(RegExp|string)[]} - An array of either regular expressions or named intents can be passed to match the users utterance in a number of possible ways. The rule generating the highest score (best match) will be used for scoring purposes.
MessageType

Message based prompts that can be sent to a user.

  • {IMessage} - Message to send the user expressed using JSON. The message can contain attachments and suggested actions. Not all channels natively support all message properties but most channels will down render unsupported fields.
  • {IIsMessage} - An instance of the Message builder class. This class helps to localize your messages and provides helpers to aid with formatting the text portions of your message.
TextOrMessageType

Flexible range of possible prompts that can be sent to a user.

  • {string} - A simple message to send the user.
  • {string[]} - Array of possible messages to send the user. One will be chosen at random.
  • {IMessage} - Message to send the user expressed using JSON. The message can contain attachments and suggested actions. Not all channels natively support all message properties but most channels will down render unsupported fields.
  • {IIsMessage} - An instance of the Message builder class. This class helps to localize your messages and provides helpers to aid with formatting the text portions of your message.
TextType

Text based prompts that can be sent to a user.

  • {string} - A simple message to send the user.
  • {string[]} - Array of possible messages to send the user. One will be chosen at random.
ValueListType

List of text values. The values can be expressed as a pipe delimited string like "value1|value2|value3" or simple array of values.

Enums

ListStyle

Type of list to render for PromptType.choice prompt.

PromptType

Type of prompt invoked.

RecognizeMode

Controls an IntentDialogs processing of the users text utterances.

RecognizeOrder

Order in which an IntentDialogs recognizers should be evaluated.

ResumeReason

Reason codes for why a dialog was resumed.