BotFrameworkAdapter class

A BotAdapter that can connect a bot to a service endpoint. Implements IUserTokenProvider.

Extends

BotAdapter

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.

For example:

const { BotFrameworkAdapter } = require('botbuilder');

const adapter = new BotFrameworkAdapter({
    appId: process.env.MicrosoftAppId,
    appPassword: process.env.MicrosoftAppPassword
});

adapter.onTurnError = async (context, error) => {
    // Catch-all logic for errors.
};

Constructors

BotFrameworkAdapter(Partial<BotFrameworkAdapterSettings>)

Creates a new instance of the BotFrameworkAdapter class.

Properties

BotIdentityKey
ConnectorClientKey
isStreamingConnectionOpen

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

OAuthScopeKey
onTurnError
TokenApiClientCredentialsKey

Methods

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

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

continueConversation(Partial<ConversationReference>, string, (context: 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.

createConnectorClient(string)

Creates a connector client.

createConnectorClientWithIdentity(string, ClaimsIdentity)

Create a ConnectorClient with a ClaimsIdentity.

createConnectorClientWithIdentity(string, ClaimsIdentity, string)

Create a ConnectorClient with a ClaimsIdentity and an explicit audience.

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

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

createConversation(Partial<ConversationReference>, Partial<ConversationParameters>, (context: TurnContext) => Promise<void>)

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

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.

deleteConversationMember(TurnContext, string)

Asynchronously removes a member from the current conversation.

emulateOAuthCards(TurnContext | string, boolean)

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.

exchangeToken(TurnContext, string, string, TokenExchangeRequest, CoreAppCredentials)

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

getAadTokens(TurnContext, string, string[])

Asynchronously signs out the user from the token server.

getAadTokens(TurnContext, string, string[], CoreAppCredentials)
getActivityMembers(TurnContext, string)

Asynchronously lists the members of a given activity.

getConversationMembers(TurnContext)

Asynchronously lists the members of the current conversation.

getConversations(TurnContext | string, string)

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

getSignInLink(TurnContext, string, AppCredentials, string, string)

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

getSignInLink(TurnContext, string, CoreAppCredentials, string, string)
getSignInResource(TurnContext, string, string, string, CoreAppCredentials)

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

getTokenStatus(TurnContext, string, string)

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

getTokenStatus(TurnContext, string, string, CoreAppCredentials)
getUserToken(TurnContext, string, string)

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

getUserToken(TurnContext, string, string, CoreAppCredentials)
process(Request, INodeSocket, INodeBuffer, (context: TurnContext) => Promise<void>)

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

process(Request, Response, (context: TurnContext) => Promise<void>)

Process a web request by applying a logic function.

processActivity(WebRequest, WebResponse, (context: TurnContext) => Promise<any>)

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

processActivityDirect(Activity, (context: TurnContext) => Promise<any>)

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

processRequest(IReceiveRequest)

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

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.

signOutUser(TurnContext, string, string)

Asynchronously signs out the user from the token server.

signOutUser(TurnContext, string, string, CoreAppCredentials)
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.

useNamedPipe((context: TurnContext) => Promise<any>, string, number, () => void)

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

useWebSocket(WebRequest, INodeSocket, INodeBuffer, (context: TurnContext) => Promise<any>)

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

Constructor Details

BotFrameworkAdapter(Partial<BotFrameworkAdapterSettings>)

Creates a new instance of the BotFrameworkAdapter class.

new BotFrameworkAdapter(settings?: Partial<BotFrameworkAdapterSettings>)

Parameters

settings

Partial<BotFrameworkAdapterSettings>

Optional. The settings to use for this adapter instance.

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.

Property Details

BotIdentityKey

BotIdentityKey: symbol

Property Value

symbol

ConnectorClientKey

ConnectorClientKey: symbol

Property Value

symbol

isStreamingConnectionOpen

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

boolean isStreamingConnectionOpen

Property Value

boolean

OAuthScopeKey

OAuthScopeKey: symbol

Property Value

symbol

onTurnError

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

Property Value

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

TokenApiClientCredentialsKey

TokenApiClientCredentialsKey: symbol

Property Value

symbol

Method Details

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

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

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

Parameters

reference

Partial<ConversationReference>

A reference to the conversation to continue.

logic

(context: 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.

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);
   }
});

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

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>)

Parameters

reference

Partial<ConversationReference>

(xref:botframework-schema.ConversationReference) of the conversation to continue.

oAuthScope

string

The intended recipient of any sent activities or the function to call to continue the conversation.

logic

(context: TurnContext) => Promise<void>

Optional. The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

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>)

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>)

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>)

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

createConnectorClient(string)

Creates a connector client.

function createConnectorClient(serviceUrl: string)

Parameters

serviceUrl

string

The client's service URL.

Returns

ConnectorClient

Remarks

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

createConnectorClientWithIdentity(string, ClaimsIdentity)

Create a ConnectorClient with a ClaimsIdentity.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity)

Parameters

serviceUrl

string

The client's service URL.

identity

ClaimsIdentity

ClaimsIdentity

Returns

Promise<ConnectorClient>

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.

createConnectorClientWithIdentity(string, ClaimsIdentity, string)

Create a ConnectorClient with a ClaimsIdentity and an explicit audience.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity, audience: string)

Parameters

serviceUrl

string

The client's service URL.

identity

ClaimsIdentity

ClaimsIdentity

audience

string

The recipient of the ConnectorClient's messages. Normally the Bot Framework Channel Service or the AppId of another bot.

Returns

Promise<ConnectorClient>

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.

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

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

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

Parameters

reference

Partial<ConversationReference>

A reference for the conversation to create.

logic

(context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the asynchronous operation

createConversation(Partial<ConversationReference>, Partial<ConversationParameters>, (context: TurnContext) => Promise<void>)

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>)

Parameters

reference

Partial<ConversationReference>

A reference for the conversation to create.

parameters

Partial<ConversationParameters>

Parameters used when creating the conversation

logic

(context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the asynchronous 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>)

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>)

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.

deleteConversationMember(TurnContext, string)

Asynchronously removes a member from the current conversation.

function deleteConversationMember(context: TurnContext, memberId: string)

Parameters

context

TurnContext

The context object for the turn.

memberId

string

The ID of the member to remove from the conversation.

Returns

Promise<void>

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.

emulateOAuthCards(TurnContext | string, boolean)

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)

Parameters

contextOrServiceUrl

TurnContext | string

The URL of the emulator.

emulate

boolean

true to send an emulated OAuth card to the emulator; or false to not send the card.

Returns

Promise<void>

Remarks

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

exchangeToken(TurnContext, string, string, TokenExchangeRequest, CoreAppCredentials)

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

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

Parameters

context

TurnContext

Context for the current turn of conversation with the user.

connectionName

string

Name of the auth connection to use.

userId

string

The user id that will be associated with the token.

tokenExchangeRequest

TokenExchangeRequest

The exchange request details, either a token to exchange or a uri to exchange.

appCredentials

CoreAppCredentials

Optional. The CoreAppCredentials for OAuth.

Returns

Promise<TokenResponse>

getAadTokens(TurnContext, string, string[])

Asynchronously signs out the user from the token server.

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[])

Parameters

context

TurnContext

The context object for the turn.

connectionName

string

The name of the auth connection to use.

resourceUrls

string[]

The list of resource URLs to retrieve tokens for.

Returns

Promise<[key: string]: TokenResponse>

A map of the TokenResponse objects by resource URL.

getAadTokens(TurnContext, string, string[], CoreAppCredentials)

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[], oAuthAppCredentials?: CoreAppCredentials)

Parameters

context

TurnContext

connectionName

string

resourceUrls

string[]

oAuthAppCredentials

CoreAppCredentials

Returns

Promise<[key: string]: TokenResponse>

getActivityMembers(TurnContext, string)

Asynchronously lists the members of a given activity.

function getActivityMembers(context: TurnContext, activityId?: string)

Parameters

context

TurnContext

The context object for the turn.

activityId

string

Optional. The ID of the activity to get the members of. If not specified, the current activity ID is used.

Returns

Promise<ChannelAccount[]>

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.

getConversationMembers(TurnContext)

Asynchronously lists the members of the current conversation.

function getConversationMembers(context: TurnContext)

Parameters

context

TurnContext

The context object for the turn.

Returns

Promise<ChannelAccount[]>

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.

getConversations(TurnContext | string, string)

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

function getConversations(contextOrServiceUrl: TurnContext | string, continuationToken?: string)

Parameters

contextOrServiceUrl

TurnContext | string

The URL of the channel server to query or a TurnContext object from a conversation on the channel.

continuationToken

string

Optional. The continuation token from the previous page of results. Omit this parameter or use undefined to retrieve the first page of results.

Returns

Promise<ConversationsResult>

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)

Parameters

context

TurnContext

The context object for the turn.

connectionName

string

The name of the auth connection to use.

oAuthAppCredentials

AppCredentials

AppCredentials for OAuth.

userId

string

The user id that will be associated with the token.

finalRedirect

string

The final URL that the OAuth flow will redirect to.

Returns

Promise<string>

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

Parameters

context

TurnContext

connectionName

string

oAuthAppCredentials

CoreAppCredentials

userId

string

finalRedirect

string

Returns

Promise<string>

getSignInResource(TurnContext, string, string, string, CoreAppCredentials)

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)

Parameters

context

TurnContext

The context object for the turn.

connectionName

string

The name of the auth connection to use.

userId

string

The user id that will be associated with the token.

finalRedirect

string

The final URL that the OAuth flow will redirect to.

appCredentials

CoreAppCredentials

Returns

Promise<SignInUrlResponse>

The BotSignInGetSignInResourceResponse object.

getTokenStatus(TurnContext, string, string)

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

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string)

Parameters

context

TurnContext

The context object for the turn.

userId

string

Optional. If present, the ID of the user to retrieve the token status for. Otherwise, the ID of the user who sent the current activity is used.

includeFilter

string

Optional. A comma-separated list of connection's to include. If present, the includeFilter parameter limits the tokens this method returns.

Returns

Promise<TokenStatus[]>

The TokenStatus objects retrieved.

getTokenStatus(TurnContext, string, string, CoreAppCredentials)

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string, oAuthAppCredentials?: CoreAppCredentials)

Parameters

context

TurnContext

userId

string

includeFilter

string

oAuthAppCredentials

CoreAppCredentials

Returns

Promise<TokenStatus[]>

getUserToken(TurnContext, string, string)

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

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string)

Parameters

context

TurnContext

The context object for the turn.

connectionName

string

The name of the auth connection to use.

magicCode

string

Optional. The validation code the user entered.

Returns

Promise<TokenResponse>

A TokenResponse object that contains the user token.

getUserToken(TurnContext, string, string, CoreAppCredentials)

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string, oAuthAppCredentials?: CoreAppCredentials)

Parameters

context

TurnContext

connectionName

string

magicCode

string

oAuthAppCredentials

CoreAppCredentials

Returns

Promise<TokenResponse>

process(Request, INodeSocket, INodeBuffer, (context: TurnContext) => Promise<void>)

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>)

Parameters

req
Request

An incoming HTTP Request

socket

INodeSocket

The corresponding INodeSocket

head

INodeBuffer

The corresponding INodeBuffer

logic

(context: TurnContext) => Promise<void>

The logic function to apply

Returns

Promise<void>

a promise representing the asynchronous operation.

process(Request, Response, (context: TurnContext) => Promise<void>)

Process a web request by applying a logic function.

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

Parameters

req
Request

The corresponding HTTP Response

res
Response
logic

(context: TurnContext) => Promise<void>

The logic function to apply

Returns

Promise<void>

a promise representing the asynchronous operation.

processActivity(WebRequest, WebResponse, (context: TurnContext) => Promise<any>)

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>)

Parameters

req
WebRequest

An Express or Restify style request object.

res
WebResponse

An Express or Restify style response object.

logic

(context: TurnContext) => Promise<any>

The function to call at the end of the middleware pipeline.

Returns

Promise<void>

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.

Tip

If you see the error TypeError: Cannot perform 'set' on a proxy that has been revoked in your bot's console output, the likely cause is that an async function was used without using the await keyword. Make sure all async functions use await!

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`);
       }
   });
});

processActivityDirect(Activity, (context: TurnContext) => Promise<any>)

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

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

Parameters

activity

Activity

The activity to process.

logic

(context: TurnContext) => Promise<any>

The function to call at the end of the middleware pipeline.

Returns

Promise<void>

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.

processRequest(IReceiveRequest)

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)

Parameters

request

IReceiveRequest

A ReceiveRequest from the connected channel.

Returns

Promise<StreamingResponse>

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

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

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.

signOutUser(TurnContext, string, string)

Asynchronously signs out the user from the token server.

function signOutUser(context: TurnContext, connectionName?: string, userId?: string)

Parameters

context

TurnContext

The context object for the turn.

connectionName

string

The name of the auth connection to use.

userId

string

The ID of user to sign out.

Returns

Promise<void>

signOutUser(TurnContext, string, string, CoreAppCredentials)

function signOutUser(context: TurnContext, connectionName?: string, userId?: string, oAuthAppCredentials?: CoreAppCredentials)

Parameters

context

TurnContext

connectionName

string

userId

string

oAuthAppCredentials

CoreAppCredentials

Returns

Promise<void>

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>)

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

Parameters

middlewares

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

Returns

this

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.

useNamedPipe((context: TurnContext) => Promise<any>, string, number, () => void)

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)

Parameters

logic

(context: TurnContext) => Promise<any>

The logic that will handle incoming requests.

pipeName

string

The name of the named pipe to use when creating the server.

retryCount

number

Number of times to attempt to bind incoming and outgoing pipe

onListen

() => void

Optional callback that fires once when server is listening on both incoming and outgoing pipe

Returns

Promise<void>

useWebSocket(WebRequest, INodeSocket, INodeBuffer, (context: TurnContext) => Promise<any>)

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>)

Parameters

req
WebRequest

The connection request.

socket

INodeSocket

The raw socket connection between the bot (server) and channel/caller (client).

head

INodeBuffer

The first packet of the upgraded stream.

logic

(context: TurnContext) => Promise<any>

The logic that handles incoming streaming requests for the lifetime of the WebSocket connection.

Returns

Promise<void>