BotFrameworkAdapter class

Creates a new instance of the BotFrameworkAdapter class.

new BotFrameworkAdapter(settings?: Partial<BotFrameworkAdapterSettings>)

Parameters

Remarks

If the settings parameter does not include channelService or openIdMetadata values, the constructor checks the process' environment variables for these values. These values may be set when a bot is provisioned on Azure and if so are required for the bot to work properly in the global cloud or in a national cloud.

The BotFrameworkAdapterSettings class defines the available adapter settings.

Used in streaming contexts to check if the streaming connection is still open for the bot to send activities.

boolean isStreamingConnectionOpen

Property Value

True if the streaming connection is open, otherwise false.

TokenApiClientCredentialsKey: symbol

Property Value

BotIdentityKey: symbol

Property Value

Inherited From BotAdapter.BotIdentityKey

ConnectorClientKey: symbol

Property Value

Inherited From BotAdapter.ConnectorClientKey

OAuthScopeKey: symbol

Property Value

Inherited From BotAdapter.OAuthScopeKey

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

Property Value

Inherited From BotAdapter.onTurnError

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

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

Parameters

Returns

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.

To send a proactive message:

1. Save a copy of a ConversationReference from an incoming activity. For example, you can store the conversation reference in a database.
2. Call this method to resume the conversation at a later time. Use the saved reference to access the conversation.
3. On success, the adapter generates a TurnContext object and calls the logic function handler. Use the logic function to send the proactive message.

To copy the reference from any incoming activity in the conversation, use the TurnContext.getConversationReference method.

This method is similar to the processActivity method. The adapter creates a TurnContext and routes it through its middleware before calling the logic handler. The created activity will have a type of 'event' and a name of 'continueConversation'.

For example:

server.post('/api/notifyUser', async (req, res) => {
   // Lookup previously saved conversation reference.
   const reference = await findReference(req.body.refId);

   // Proactively notify the user.
   if (reference) {
      await adapter.continueConversation(reference, async (context) => {
         await context.sendActivity(req.body.message);
      });
      res.send(200);
   } else {
      res.send(404);
   }
});

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

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

Parameters

Returns

Creates a connector client.

function createConnectorClient(serviceUrl: string): ConnectorClient

Parameters

Returns

The ConnectorClient instance.

Remarks

Override this in a derived class to create a mock connector client for unit testing.

Create a ConnectorClient with a ClaimsIdentity.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity): Promise<ConnectorClient>

Parameters

Returns

Remarks

If the ClaimsIdentity contains the claims for a Skills request, create a ConnectorClient for use with Skills. Derives the correct audience from the ClaimsIdentity, or the instance's credentials property.

Create a ConnectorClient with a ClaimsIdentity and an explicit audience.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity, audience: string): Promise<ConnectorClient>

Parameters

Returns

Remarks

If the trimmed audience is not a non-zero length string, the audience will be derived from the ClaimsIdentity or the instance's credentials property.

Asynchronously creates and starts a conversation with a user on a channel.

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

Parameters

Returns

a promise representing the asynchronous operation

Asynchronously creates and starts a conversation with a user on a channel.

function createConversation(reference: Partial<ConversationReference>, parameters: Partial<ConversationParameters>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

Returns

a promise representing the asynchronous operation

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

Returns

Remarks

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

Asynchronously removes a member from the current conversation.

function deleteConversationMember(context: TurnContext, memberId: string): Promise<void>

Parameters

Returns

Remarks

Remove a member's identity information from the conversation.

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

Asynchronously sends an emulated OAuth card for a channel. This method supports the framework and is not intended to be called directly for your code.

function emulateOAuthCards(contextOrServiceUrl: TurnContext | string, emulate: boolean): Promise<void>

Parameters

Returns

Remarks

When testing a bot in the Bot Framework Emulator, this method can emulate the OAuth card interaction.

Asynchronously Performs a token exchange operation such as for single sign-on.

function exchangeToken(context: TurnContext, connectionName: string, userId: string, tokenExchangeRequest: TokenExchangeRequest, appCredentials?: CoreAppCredentials): Promise<TokenResponse>

Parameters

Returns

Asynchronously signs out the user from the token server.

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[]): Promise<[key: string]: TokenResponse>

Parameters

Returns

A map of the TokenResponse objects by resource URL.

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[], oAuthAppCredentials?: CoreAppCredentials): Promise<[key: string]: TokenResponse>

Parameters

Returns

Asynchronously lists the members of a given activity.

function getActivityMembers(context: TurnContext, activityId?: string): Promise<ChannelAccount[]>

Parameters

Returns

An array of ChannelAccount objects for the users involved in a given activity.

Remarks

Returns an array of ChannelAccount objects for the users involved in a given activity.

This is different from getConversationMembers in that it will return only those users directly involved in the activity, not all members of the conversation.

Asynchronously lists the members of the current conversation.

function getConversationMembers(context: TurnContext): Promise<ChannelAccount[]>

Parameters

Returns

An array of ChannelAccount objects for all users currently involved in a conversation.

Remarks

Returns an array of ChannelAccount objects for all users currently involved in a conversation.

This is different from getActivityMembers in that it will return all members of the conversation, not just those directly involved in a specific activity.

For the specified channel, asynchronously gets a page of the conversations in which this bot has participated.

function getConversations(contextOrServiceUrl: TurnContext | string, continuationToken?: string): Promise<ConversationsResult>

Parameters

Returns

A ConversationsResult object containing a page of results and a continuation token.

Remarks

The the return value's conversations property contains a page of ConversationMembers objects. Each object's id is the ID of a conversation in which the bot has participated on this channel. This method can be called from outside the context of a conversation, as only the bot's service URL and credentials are required.

The channel batches results in pages. If the result's continuationToken property is not empty, then there are more pages to get. Use the returned token to get the next page of results. If the contextOrServiceUrl parameter is a TurnContext, the URL of the channel server is retrieved from contextOrServiceUrl.activity.serviceUrl.

Asynchronously gets a sign-in link from the token server that can be sent as part of a SigninCard.

function getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: AppCredentials, userId?: string, finalRedirect?: string): Promise<string>

Parameters

Returns

function getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: CoreAppCredentials, userId?: string, finalRedirect?: string): Promise<string>

Parameters

Returns

Asynchronously Get the raw signin resource to be sent to the user for signin.

function getSignInResource(context: TurnContext, connectionName: string, userId?: string, finalRedirect?: string, appCredentials?: CoreAppCredentials): Promise<SignInUrlResponse>

Parameters

Returns

The BotSignInGetSignInResourceResponse object.

Asynchronously retrieves the token status for each configured connection for the given user.

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string): Promise<TokenStatus[]>

Parameters

Returns

The TokenStatus objects retrieved.

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenStatus[]>

Parameters

Returns

Asynchronously attempts to retrieve the token for a user that's in a login flow.

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string): Promise<TokenResponse>

Parameters

Returns

A TokenResponse object that contains the user token.

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenResponse>

Parameters

Returns

Handle a web socket connection by applying a logic function to each streaming request.

function process(req: Request, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

Returns

a promise representing the asynchronous operation.

Process a web request by applying a logic function.

function process(req: Request, res: Response, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

Returns

a promise representing the asynchronous operation.

Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.

function processActivity(req: WebRequest, res: WebResponse, logic: (context: TurnContext) => Promise<any>): Promise<void>

Parameters

Returns

Remarks

This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:

1. Parses and authenticates an incoming request.
   • The activity is read from the body of the incoming request. An error will be returned if the activity can't be parsed.
   • The identity of the sender is authenticated as either the Emulator or a valid Microsoft server, using the bot's appId and appPassword. The request is rejected if the sender's identity is not verified.
2. Creates a TurnContext object for the received activity.
   • This object is wrapped with a revocable proxy.
   • When this method completes, the proxy is revoked.
3. Sends the turn context through the adapter's middleware pipeline.
4. Sends the turn context to the logic function.
   • The bot may perform additional routing or processing at this time. Returning a promise (or providing an async handler) will cause the adapter to wait for any asynchronous operations to complete.
   • After the logic function completes, the promise chain set up by the middleware is resolved.

Middleware can short circuit a turn. When this happens, subsequent middleware and the logic function is not called; however, all middleware prior to this point still run to completion. For more information about the middleware pipeline, see the how bots work and middleware articles. Use the adapter's use method to add middleware to the adapter.

For example:

server.post('/api/messages', (req, res) => {
   // Route received request to adapter for processing
   adapter.processActivity(req, res, async (context) => {
       // Process any messages received
       if (context.activity.type === ActivityTypes.Message) {
           await context.sendActivity(`Hello World`);
       }
   });
});

Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.

function processActivityDirect(activity: Activity, logic: (context: TurnContext) => Promise<any>): Promise<void>

Parameters

Returns

Remarks

This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:

1. Creates a TurnContext object for the received activity.
   • This object is wrapped with a revocable proxy.
   • When this method completes, the proxy is revoked.
2. Sends the turn context through the adapter's middleware pipeline.
3. Sends the turn context to the logic function.
   • The bot may perform additional routing or processing at this time. Returning a promise (or providing an async handler) will cause the adapter to wait for any asynchronous operations to complete.
   • After the logic function completes, the promise chain set up by the middleware is resolved.

Middleware can short circuit a turn. When this happens, subsequent middleware and the logic function is not called; however, all middleware prior to this point still run to completion. For more information about the middleware pipeline, see the how bots work and middleware articles. Use the adapter's use method to add middleware to the adapter.

Checks the validity of the request and attempts to map it the correct virtual endpoint, then generates and returns a response if appropriate.

function processRequest(request: IReceiveRequest): Promise<StreamingResponse>

Parameters

Returns

A response created by the BotAdapter to be sent to the client that originated the request.

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

Returns

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.

Asynchronously signs out the user from the token server.

function signOutUser(context: TurnContext, connectionName?: string, userId?: string): Promise<void>

Parameters

Returns

function signOutUser(context: TurnContext, connectionName?: string, userId?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<void>

Parameters

Returns

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

Returns

A Promise representing the ResourceResponse for the operation.

Remarks

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

Connects the handler to a Named Pipe server and begins listening for incoming requests.

function useNamedPipe(logic: (context: TurnContext) => Promise<any>, pipeName?: string, retryCount?: number, onListen?: () => void): Promise<void>

Parameters

Returns

Process the initial request to establish a long lived connection via a streaming server.

function useWebSocket(req: WebRequest, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<any>): Promise<void>

Parameters

Returns

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

Returns

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

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

Returns

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

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

Returns

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

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

Returns

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.

Inherited From BotAdapter.createConversationAsync

Adds middleware to the adapter's pipeline.

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

Parameters

Returns

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.

Inherited From BotAdapter.use