Application class

Package:

@microsoft/teams-ai

Application class for routing and processing incoming requests.

Remarks

The Application object replaces the traditional ActivityHandler that a bot would use. It supports a simpler fluent style of authoring bots versus the inheritance based approach used by the ActivityHandler class.

Additionally, it has built-in support for calling into the SDK's AI system and can be used to create bots that leverage Large Language Models (LLM) and other AI capabilities.

Constructors

Application<TState>(Partial<ApplicationOptions<TState>>)

Creates a new Application instance.

Properties

adapter	The bot's adapter.
adaptiveCards	Fluent interface for accessing Adaptive Card specific features.
ai	Fluent interface for accessing AI specific features.
authentication	This property is only available if the Application was configured with authentication options. An exception will be thrown if you attempt to access it otherwise.
meetings	Fluent interface for accessing Meetings specific features.
messageExtensions	Fluent interface for accessing Message Extensions' specific features.
options	The application's configured options.
taskModules	Fluent interface for accessing Task Module specific features.

Methods

activity(string | RegExp | Selector | (string | RegExp | Selector)[], (context: TurnContext, state: TState) => Promise<void>)	Handles incoming activities of a given type.
addRoute(Selector, RouteHandler<TState>, boolean)	Adds a new route to the application.
conversationUpdate(ConversationUpdateEvents, (context: TurnContext, state: TState) => Promise<void>)	Handles conversation update events.
error((context: TurnContext, error: Error) => Promise<void>)	Sets the bot's error handler
feedbackLoop((context: TurnContext, state: TState, feedbackLoopData: FeedbackLoopData) => Promise<void>)	Registers a handler for feedbackloop events when a user clicks the thumbsup or thumbsdown button on a response from AI. enable_feedback_loop must be set to true in the AI Module.
fileConsentAccept((context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>)	Registers a handler to process when a file consent card is accepted by the user.
fileConsentDecline((context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>)	Registers a handler to process when a file consent card is declined by the user.
getTokenOrStartSignIn(TurnContext, TState, string)	If the user is signed in, get the access token. If not, triggers the sign in flow for the provided authentication setting name and returns. In this case, the bot should end the turn until the sign in flow is completed.
handoff((context: TurnContext, state: TState, continuation: string) => Promise<void>)	Registers a handler to handoff conversations from one copilot to another.
message(string | RegExp | Selector | (string | RegExp | Selector)[], (context: TurnContext, state: TState) => Promise<void>)	Handles incoming messages with a given keyword.
messageEventUpdate(TeamsMessageEvents, (context: TurnContext, state: TState) => Promise<void>)
messageReactions(MessageReactionEvents, (context: TurnContext, state: TState) => Promise<void>)	Handles message reaction events.
O365ConnectorCardAction((context: TurnContext, state: TState, query: O365ConnectorCardActionQuery) => Promise<void>)	Registers a handler to process when a O365 Connector Card Action activity is received from the user.
run(TurnContext)	Dispatches an incoming activity to a handler registered with the application.
sendProactiveActivity(Partial<Activity>, string | Partial<Activity>, string, string)
sendProactiveActivity(Partial<ConversationReference>, string | Partial<Activity>, string, string)
sendProactiveActivity(TurnContext, string | Partial<Activity>, string, string)	Sends a proactive activity to an existing conversation the bot is a member of.
startTypingTimer(TurnContext)	Manually start a timer to periodically send "typing" activities.
stopTypingTimer()	Manually stop the typing timer.
teamsReadReceipt((context: TurnContext, state: TState, readReceiptInfo: ReadReceiptInfo) => Promise<void>)	Adds a handler for Teams' readReceiptInfo event
turn(TurnEvents | TurnEvents[], (context: TurnContext, state: TState) => Promise<boolean>)	Registers a turn event handler.

Constructor Details

Application<TState>(Partial<ApplicationOptions<TState>>)

Creates a new Application instance.

new Application(options?: Partial<ApplicationOptions<TState>>)

Parameters

options

Partial<ApplicationOptions<TState>>

Optional. Options used to configure the application.

Property Details

adapter

The bot's adapter.

BotAdapter adapter

Property Value

BotAdapter

The bot's adapter that is configured for the application.

adaptiveCards

Fluent interface for accessing Adaptive Card specific features.

AdaptiveCards<TState> adaptiveCards

Property Value

AdaptiveCards<TState>

The AdaptiveCards instance.

ai

Fluent interface for accessing AI specific features.

AI<TState> ai

Property Value

AI<TState>

The AI instance.

authentication

This property is only available if the Application was configured with authentication options. An exception will be thrown if you attempt to access it otherwise.

AuthenticationManager<TState> authentication

Property Value

AuthenticationManager<TState>

The Authentication instance.

meetings

Fluent interface for accessing Meetings specific features.

Meetings<TState> meetings

Property Value

Meetings<TState>

The Meetings instance.

messageExtensions

Fluent interface for accessing Message Extensions' specific features.

MessageExtensions<TState> messageExtensions

Property Value

MessageExtensions<TState>

The MessageExtensions instance.

options

The application's configured options.

ApplicationOptions<TState> options

Property Value

ApplicationOptions<TState>

The application's configured options.

taskModules

Fluent interface for accessing Task Module specific features.

TaskModules<TState> taskModules

Property Value

TaskModules<TState>

The TaskModules instance.

Method Details

activity(string | RegExp | Selector | (string | RegExp | Selector)[], (context: TurnContext, state: TState) => Promise<void>)

Handles incoming activities of a given type.

function activity(type: string | RegExp | Selector | (string | RegExp | Selector)[], handler: (context: TurnContext, state: TState) => Promise<void>): Application<TState>

Parameters

type

string | RegExp | Selector | (string | RegExp | Selector)[]

Name of the activity type to match or a regular expression to match against the incoming activity type. An array of type names or expression can also be passed in.

handler

(context: TurnContext, state: TState) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

addRoute(Selector, RouteHandler<TState>, boolean)

Adds a new route to the application.

function addRoute(selector: Selector, handler: RouteHandler<TState>, isInvokeRoute?: boolean): Application<TState>

Parameters

selector

Selector

Function thats used to select a route. The function should return true to trigger the route.

handler

RouteHandler<TState>

Function to call when the route is triggered.

isInvokeRoute

boolean

Optional. Boolean indicating if the RouteSelector is for an activity that uses "invoke" which require special handling. Defaults to false.

Returns

Application<TState>

The application instance for chaining purposes.

Remarks

Developers won't typically need to call this method directly as it's used internally by all of the fluent interfaces to register routes for their specific activity types.

Routes will be matched in the order they're added to the application. The first selector to return true when an activity is received will have its handler called.

Invoke-based activities receive special treatment and are matched separately as they typically have shorter execution timeouts.

conversationUpdate(ConversationUpdateEvents, (context: TurnContext, state: TState) => Promise<void>)

Handles conversation update events.

function conversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>): Application<TState>

Parameters

event

ConversationUpdateEvents

Name of the conversation update event to handle.

handler

(context: TurnContext, state: TState) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

error((context: TurnContext, error: Error) => Promise<void>)

Sets the bot's error handler

function error(handler: (context: TurnContext, error: Error) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, error: Error) => Promise<void>

Function to call when an error is encountered.

Returns

Application<TState>

The application instance for chaining purposes.

feedbackLoop((context: TurnContext, state: TState, feedbackLoopData: FeedbackLoopData) => Promise<void>)

Registers a handler for feedbackloop events when a user clicks the thumbsup or thumbsdown button on a response from AI. enable_feedback_loop must be set to true in the AI Module.

function feedbackLoop(handler: (context: TurnContext, state: TState, feedbackLoopData: FeedbackLoopData) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, feedbackLoopData: FeedbackLoopData) => Promise<void>

Function to call when the route is triggered

Returns

Application<TState>

The application instance for chaining purposes.

fileConsentAccept((context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>)

Registers a handler to process when a file consent card is accepted by the user.

function fileConsentAccept(handler: (context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

fileConsentDecline((context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>)

Registers a handler to process when a file consent card is declined by the user.

function fileConsentDecline(handler: (context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, fileConsentResponse: FileConsentCardResponse) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

getTokenOrStartSignIn(TurnContext, TState, string)

If the user is signed in, get the access token. If not, triggers the sign in flow for the provided authentication setting name and returns. In this case, the bot should end the turn until the sign in flow is completed.

function getTokenOrStartSignIn(context: TurnContext, state: TState, settingName: string): Promise<undefined | string>

Parameters

context

TurnContext

The context for the current turn with the user.

state

TState

The current state of the conversation.

settingName

string

The name of the authentication setting.

Returns

Promise<undefined | string>

The token for the user if they are signed in, otherwise undefined.

handoff((context: TurnContext, state: TState, continuation: string) => Promise<void>)

Registers a handler to handoff conversations from one copilot to another.

function handoff(handler: (context: TurnContext, state: TState, continuation: string) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, continuation: string) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

message(string | RegExp | Selector | (string | RegExp | Selector)[], (context: TurnContext, state: TState) => Promise<void>)

Handles incoming messages with a given keyword.

function message(keyword: string | RegExp | Selector | (string | RegExp | Selector)[], handler: (context: TurnContext, state: TState) => Promise<void>): Application<TState>

Parameters

keyword

string | RegExp | Selector | (string | RegExp | Selector)[]

Substring of text or a regular expression to match against the text of an incoming message. An array of keywords or expression can also be passed in.

handler

(context: TurnContext, state: TState) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

Remarks

This method provides a simple way to have a bot respond anytime a user sends your bot a message with a specific word or phrase.

For example, you can easily clear the current conversation anytime a user sends "/reset":

bot.message('/reset', async (context, state) => {
    await state.conversation.delete();
    await context.sendActivity(`I have reset your state.`);
});

messageEventUpdate(TeamsMessageEvents, (context: TurnContext, state: TState) => Promise<void>)

function messageEventUpdate(event: TeamsMessageEvents, handler: (context: TurnContext, state: TState) => Promise<void>): Application<TState>

Parameters

event

TeamsMessageEvents

handler

(context: TurnContext, state: TState) => Promise<void>

Returns

Application<TState>

messageReactions(MessageReactionEvents, (context: TurnContext, state: TState) => Promise<void>)

Handles message reaction events.

function messageReactions(event: MessageReactionEvents, handler: (context: TurnContext, state: TState) => Promise<void>): Application<TState>

Parameters

event

MessageReactionEvents

Name of the message reaction event(s) to handle.

handler

(context: TurnContext, state: TState) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

O365ConnectorCardAction((context: TurnContext, state: TState, query: O365ConnectorCardActionQuery) => Promise<void>)

Registers a handler to process when a O365 Connector Card Action activity is received from the user.

function O365ConnectorCardAction(handler: (context: TurnContext, state: TState, query: O365ConnectorCardActionQuery) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, query: O365ConnectorCardActionQuery) => Promise<void>

Function to call when the route is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

run(TurnContext)

Dispatches an incoming activity to a handler registered with the application.

function run(turnContext: TurnContext): Promise<boolean>

Parameters

turnContext

TurnContext

Context class for the current turn of conversation with the user.

Returns

Promise<boolean>

True if the activity was successfully dispatched to a handler. False if no matching handlers could be found.

Remarks

This method should be called from your bot's "turn handler" (its primary message handler)

server.post('/api/messages', async (req, res) => {
   await adapter.processActivity(req, res, async (context) => {
     await bot.run(context);
  });
});

sendProactiveActivity(Partial<Activity>, string | Partial<Activity>, string, string)

function sendProactiveActivity(activity: Partial<Activity>, activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<undefined | ResourceResponse>

Parameters

activity

Partial<Activity>

activityOrText

string | Partial<Activity>

speak

string

inputHint

string

Returns

Promise<undefined | ResourceResponse>

sendProactiveActivity(Partial<ConversationReference>, string | Partial<Activity>, string, string)

function sendProactiveActivity(conversationReference: Partial<ConversationReference>, activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<undefined | ResourceResponse>

Parameters

conversationReference

Partial<ConversationReference>

activityOrText

string | Partial<Activity>

speak

string

inputHint

string

Returns

Promise<undefined | ResourceResponse>

sendProactiveActivity(TurnContext, string | Partial<Activity>, string, string)

Sends a proactive activity to an existing conversation the bot is a member of.

function sendProactiveActivity(context: TurnContext, activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<undefined | ResourceResponse>

Parameters

context

TurnContext

Context of the conversation to proactively message. This can be derived from either a TurnContext, ConversationReference, or Activity.

activityOrText

string | Partial<Activity>

Activity or message to send to the conversation.

speak

string

Optional. Text to speak for channels that support voice.

inputHint

string

Optional. Input hint for channels that support voice.

Returns

Promise<undefined | ResourceResponse>

A Resource response containing the ID of the activity that was sent.

Remarks

This method provides a simple way to send a proactive message to a conversation the bot is a member of.

Use of the method requires you configure the Application with the adapter.appId options. An exception will be thrown if either is missing.

startTypingTimer(TurnContext)

Manually start a timer to periodically send "typing" activities.

function startTypingTimer(context: TurnContext)

Parameters

context

TurnContext

The context for the current turn with the user.

Remarks

The timer waits 1000ms to send its initial "typing" activity and then send an additional "typing" activity every 1000ms. The timer will automatically end once an outgoing activity has been sent. If the timer is already running or the current activity, is not a "message" the call is ignored.

stopTypingTimer()

Manually stop the typing timer.

function stopTypingTimer()

Remarks

If the timer isn't running nothing happens.

teamsReadReceipt((context: TurnContext, state: TState, readReceiptInfo: ReadReceiptInfo) => Promise<void>)

Adds a handler for Teams' readReceiptInfo event

function teamsReadReceipt(handler: (context: TurnContext, state: TState, readReceiptInfo: ReadReceiptInfo) => Promise<void>): Application<TState>

Parameters

handler

(context: TurnContext, state: TState, readReceiptInfo: ReadReceiptInfo) => Promise<void>

Function to call when the event is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

turn(TurnEvents | TurnEvents[], (context: TurnContext, state: TState) => Promise<boolean>)

Registers a turn event handler.

function turn(event: TurnEvents | TurnEvents[], handler: (context: TurnContext, state: TState) => Promise<boolean>): Application<TState>

Parameters

event

TurnEvents | TurnEvents[]

Name of the turn event to handle.

handler

(context: TurnContext, state: TState) => Promise<boolean>

Function to call when the event is triggered.

Returns

Application<TState>

The application instance for chaining purposes.

Remarks

Turn events let you do something before or after a turn is run. Returning false from beforeTurn lets you prevent the turn from running and returning false from afterTurn lets you prevent the bots state from being saved.

Returning false from beforeTurn does result in the bots state being saved which lets you track the reason why the turn was not processed. It also means you can use beforeTurn as a way to call into the dialog system. For example, you could use the OAuthPrompt to sign the user in before allowing the AI system to run.