BotAdapter class

Package:

botbuilder-core

Defines the core behavior of a bot adapter that can connect a bot to a service endpoint.

Remarks

The bot adapter encapsulates authentication processes and sends activities to and receives activities from the Bot Connector Service. When your bot receives an activity, the adapter creates a turn context object, passes it to your bot application logic, and sends responses back to the user's channel.

The adapter processes and directs incoming activities in through the bot middleware pipeline to your bot logic and then back out again. As each activity flows in and out of the bot, each piece of middleware can inspect or act upon the activity, both before and after the bot logic runs. Use the use method to add Middleware objects to your adapter's middleware collection.

For more information, see the articles on How bots work and Middleware.

Properties

BotIdentityKey
ConnectorClientKey
OAuthScopeKey
onTurnError	Gets or sets an error handler that can catch exceptions in the middleware or application. Sets an error handler that can catch exceptions in the middleware or application.

Methods

continueConversation(Partial<ConversationReference>, (revocableContext: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, string, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
continueConversationAsync(string, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
createConversationAsync(string, string, string, string, ConversationParameters, (context: TurnContext) => Promise<void>)	Creates a conversation on the specified channel.
deleteActivity(TurnContext, Partial<ConversationReference>)	Asynchronously deletes an existing activity. This interface supports the framework and is not intended to be called directly for your code. Use TurnContext.deleteActivity to delete an activity from your bot code.
sendActivities(TurnContext, Partial<Activity>[])	Asynchronously sends a set of outgoing activities to a channel server. This method supports the framework and is not intended to be called directly for your code. Use the turn context's sendActivity or sendActivities method from your bot code.
updateActivity(TurnContext, Partial<Activity>)	Asynchronously replaces a previous activity with an updated version. This interface supports the framework and is not intended to be called directly for your code. Use TurnContext.updateActivity to update an activity from your bot code.
use((context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[])	Adds middleware to the adapter's pipeline.

Property Details

BotIdentityKey

BotIdentityKey: symbol

Property Value

symbol

ConnectorClientKey

ConnectorClientKey: symbol

Property Value

symbol

OAuthScopeKey

OAuthScopeKey: symbol

Property Value

symbol

onTurnError

Gets or sets an error handler that can catch exceptions in the middleware or application. Sets an error handler that can catch exceptions in the middleware or application.

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

Property Value

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

A promise representing the async operation.

Remarks

The error handler is called with these parameters:

Name	Type	Description
context	TurnContext	The context object for the turn.
error	Error	The Node.js error thrown.

Method Details

continueConversation(Partial<ConversationReference>, (revocableContext: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversation(reference: Partial<ConversationReference>, logic: (revocableContext: TurnContext) => Promise<void>): Promise<void>

Parameters

reference

Partial<ConversationReference>

A reference to the conversation to continue.

logic

(revocableContext: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

Remarks

This is often referred to as a proactive notification, the bot can proactively send a message to a conversation or user without waiting for an incoming message. For example, a bot can use this method to send notifications or coupons to a user.

continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

claimsIdentity

ClaimsIdentity

A ClaimsIdentity for the conversation.

reference

Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

logic

(context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, string, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, audience: string, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

claimsIdentity

ClaimsIdentity

A ClaimsIdentity for the conversation.

reference

Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

audience

string

A value signifying the recipient of the proactive message.

logic

(context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

continueConversationAsync(string, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(botAppId: string, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

botAppId

string

The application ID of the bot. This parameter is ignored in single tenant the Adapters (Console,Test, etc) but is critical to the BotFrameworkAdapter which is multi-tenant aware.

reference

Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

logic

(context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

createConversationAsync(string, string, string, string, ConversationParameters, (context: TurnContext) => Promise<void>)

Creates a conversation on the specified channel.

function createConversationAsync(_botAppId: string, _channelId: string, _serviceUrl: string, _audience: string, _conversationParameters: ConversationParameters, _logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

_botAppId

string

The application ID of the bot.

_channelId

string

The ID for the channel.

_serviceUrl

string

The ID for the channel.

_audience

string

The audience for the connector.

_conversationParameters

ConversationParameters

The conversation information to use to create the conversation

_logic

(context: TurnContext) => Promise<void>

The method to call for the resulting bot turn.

Returns

Promise<void>

A promise that represents the asynchronous operation

Remarks

To start a conversation, your bot must know its account information and the user's account information on that channel. Most _channels only support initiating a direct message (non-group) conversation.

The adapter attempts to create a new conversation on the channel, and then sends a conversationUpdate activity through its middleware pipeline to the logic method.

If the conversation is established with the specified users, the ID of the activity's converstion will contain the ID of the new conversation.

deleteActivity(TurnContext, Partial<ConversationReference>)

Asynchronously deletes an existing activity. This interface supports the framework and is not intended to be called directly for your code. Use TurnContext.deleteActivity to delete an activity from your bot code.

function deleteActivity(context: TurnContext, reference: Partial<ConversationReference>): Promise<void>

Parameters

context

TurnContext

The context object for the turn.

reference

Partial<ConversationReference>

Conversation reference information for the activity to delete.

Returns

Promise<void>

Remarks

Not all channels support this operation. For channels that don't, this call may throw an exception.

sendActivities(TurnContext, Partial<Activity>[])

Asynchronously sends a set of outgoing activities to a channel server. This method supports the framework and is not intended to be called directly for your code. Use the turn context's sendActivity or sendActivities method from your bot code.

function sendActivities(context: TurnContext, activities: Partial<Activity>[]): Promise<ResourceResponse[]>

Parameters

context

TurnContext

The context object for the turn.

activities

Partial<Activity>[]

The activities to send.

Returns

Promise<ResourceResponse[]>

An array of ResourceResponse

Remarks

The activities will be sent one after another in the order in which they're received. A response object will be returned for each sent activity. For message activities this will contain the ID of the delivered message.

updateActivity(TurnContext, Partial<Activity>)

Asynchronously replaces a previous activity with an updated version. This interface supports the framework and is not intended to be called directly for your code. Use TurnContext.updateActivity to update an activity from your bot code.

function updateActivity(context: TurnContext, activity: Partial<Activity>): Promise<ResourceResponse | void>

Parameters

context

TurnContext

The context object for the turn.

activity

Partial<Activity>

The updated version of the activity to replace.

Returns

Promise<ResourceResponse | void>

Remarks

Not all channels support this operation. For channels that don't, this call may throw an exception.

use((context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[])

Adds middleware to the adapter's pipeline.

function use(middlewares: (context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[]): this

Parameters

middlewares

(context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[]

The middleware or middleware handlers to add.

Returns

this

The updated adapter object.

Remarks

Middleware is added to the adapter at initialization time. Each turn, the adapter calls its middleware in the order in which you added it.