BotFrameworkAdapter Class

Defines an adapter to connect a bot to a service endpoint.

Initializes a new instance of the BotFrameworkAdapter class.

Inheritance

BotAdapter

BotFrameworkAdapter

ExtendedUserTokenProvider

BotFrameworkAdapter

ConnectorClientBuilder

BotFrameworkAdapter

Constructor

BotFrameworkAdapter(settings: BotFrameworkAdapterSettings)

Parameters

Name	Description
settings Required	BotFrameworkAdapterSettings The settings to initialize the adapter

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 context object, passes it to your bot's 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's 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.

Methods

can_process_outgoing_activity
continue_conversation	Continues a conversation with a user. and is generally found in the MicrosoftAppId parameter in config.py. :type bot_id: <xref:typing.str> :param claims_identity: The bot claims identity :type claims_identity: <xref:botframework.connector.auth.ClaimsIdentity> :param audience: :type audience: <xref:typing.str>
create_connector_client	Implementation of ConnectorClientProvider.create_connector_client.
create_conversation	Starts a new conversation with a user. Used to direct message to a member of a group.
delete_activity	Deletes an activity that was previously sent to a channel. It should be noted that not all channels support this feature. Note The activity_id of the ConversationReference identifies the activity to delete.
delete_conversation_member	Deletes a member from the current conversation.
exchange_token
exchange_token_from_credentials
get_aad_tokens	Retrieves Azure Active Directory tokens for particular resources on a configured connection. from the Activity in the TurnContext. :type user_id: str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>
get_activity_members	Lists the members of a given activity. If not specified the current activities ID will be used.
get_conversation_member	Retrieve a member of a current conversation.
get_conversation_members	Lists the members of a current conversation.
get_conversations	Lists the Conversations in which this bot has participated for a given channel server. context.activity.serviceUrl :type service_url: str
get_oauth_sign_in_link	Gets the raw sign-in link to be sent to the user for sign-in for a connection name.
get_sign_in_resource_from_user
get_sign_in_resource_from_user_and_credentials
get_token_status	Retrieves the token status for each configured connection for the given user. Blank will return token status for all configured connections. :type include_filter: str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>
get_user_token	Attempts to retrieve the token for a user that's in a login flow. :param magic_code" (Optional) user entered code to validate :str magic_code" str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>
key_for_app_credentials
key_for_connector_client
parse_request	Parses and validates request :param req: :return:
process_activity	Creates a turn context and runs the middleware pipeline for an incoming activity.
process_activity_with_identity
process_outgoing_activity
send_activities
sign_out_user	Signs the user out with the token server.
update_activity	Replaces an activity that was previously sent to a channel. It should be noted that not all channels support this feature.

can_process_outgoing_activity

can_process_outgoing_activity(activity: Activity) -> bool

Parameters

Name	Description
activity Required

continue_conversation

Continues a conversation with a user.

and is generally found in the MicrosoftAppId parameter in config.py. :type bot_id: <xref:typing.str> :param claims_identity: The bot claims identity :type claims_identity: <xref:botframework.connector.auth.ClaimsIdentity> :param audience: :type audience: <xref:typing.str>

async continue_conversation(reference: ConversationReference, callback: Callable, bot_id: str = None, claims_identity: ClaimsIdentity = None, audience: str = None)

Parameters

Name	Description
reference Required
callback Required
bot_id	default value: None
claims_identity	default value: None
audience	default value: None

Returns

Type	Description
	A task that represents the work queued to execute.

Exceptions

Type	Description
It raises an argument null exception.

Remarks

This is often referred to as the bots proactive messaging flow as it lets the bot proactively send messages to a conversation or user that are already in a communication. Scenarios such as sending notifications or coupons to a user are enabled by this function.

create_connector_client

Implementation of ConnectorClientProvider.create_connector_client.

async create_connector_client(service_url: str, identity: ClaimsIdentity = None, audience: str = None) -> ConnectorClient

Parameters

Name	Description
service_url Required	The service URL
identity	The claims identity default value: None
audience	default value: None

Returns

Type	Description
	An instance of the <xref:botbuilder.core.ConnectorClient> class

create_conversation

Starts a new conversation with a user. Used to direct message to a member of a group.

async create_conversation(reference: ConversationReference, logic: Callable[[TurnContext], Awaitable] = None, conversation_parameters: ConversationParameters = None, channel_id: str = None, service_url: str = None, credentials: AppCredentials = None)

Parameters

Name	Description
reference Required	ConversationReference The conversation reference that contains the tenant
logic	Callable The logic to use for the creation of the conversation default value: None
conversation_parameters	The information to use to create the conversation default value: None
channel_id	<xref:typing.str> The ID for the channel. default value: None
service_url	<xref:typing.str> The channel's service URL endpoint. default value: None
credentials	<xref:botframework.connector.auth.AppCredentials> The application credentials for the bot. default value: None

Returns

Type	Description
	A task representing the work queued to execute.

Exceptions

Type	Description
It raises a generic exception error.

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 conversation update activity through its middleware pipeline to the the callback method. If the conversation is established with the specified users, the ID of the activity will contain the ID of the new conversation.

delete_activity

Deletes an activity that was previously sent to a channel. It should be noted that not all channels support this feature.

Note

The activity_id of the ConversationReference identifies the activity to delete.

async delete_activity(context: TurnContext, reference: ConversationReference)

Parameters

Name	Description
context Required	The context object for the turn
reference Required	ConversationReference Conversation reference for the activity to delete

Returns

Type	Description
	A task that represents the work queued to execute

Exceptions

Type	Description
A exception error

delete_conversation_member

Deletes a member from the current conversation.

async delete_conversation_member(context: TurnContext, member_id: str) -> None

Parameters

Name	Description
context Required	TurnContext The context object for the turn
member_id Required	str The ID of the member to remove from the conversation

Returns

Type	Description
	A task that represents the work queued to execute.</returns

Exceptions

Type	Description
A exception error

exchange_token

async exchange_token(turn_context: TurnContext, connection_name: str, user_id: str, exchange_request: TokenExchangeRequest) -> TokenResponse

Parameters

Name	Description
turn_context Required
connection_name Required
user_id Required
exchange_request Required

exchange_token_from_credentials

async exchange_token_from_credentials(turn_context: TurnContext, oauth_app_credentials: AppCredentials, connection_name: str, user_id: str, exchange_request: TokenExchangeRequest) -> TokenResponse

Parameters

Name	Description
turn_context Required
oauth_app_credentials Required
connection_name Required
user_id Required
exchange_request Required

get_aad_tokens

Retrieves Azure Active Directory tokens for particular resources on a configured connection.

from the Activity in the TurnContext. :type user_id: str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>

async get_aad_tokens(context: TurnContext, connection_name: str, resource_urls: List[str], user_id: str = None, oauth_app_credentials: AppCredentials = None) -> Dict[str, TokenResponse]

Parameters

Name	Description
context Required
connection_name Required
resource_urls Required
user_id	default value: None
oauth_app_credentials	default value: None

Returns

Type	Description
Dict	Dictionary of resource Urls to the corresponding :class:'botbuilder.schema.TokenResponse`

get_activity_members

Lists the members of a given activity.

If not specified the current activities ID will be used.

async get_activity_members(context: TurnContext, activity_id: str)

Parameters

Name	Description
context Required
activity_id Required

Returns

Type	Description
	List of Members of the activity

Exceptions

Type	Description
An exception error

get_conversation_member

Retrieve a member of a current conversation.

async get_conversation_member(context: TurnContext, member_id: str) -> ChannelAccount

Parameters

Name	Description
context Required	TurnContext The context object for the turn
member_id Required	str The member Id

Returns

Type	Description
	A member of the current conversation

Exceptions

Type	Description
<xref:A TypeError if missing member_id>, <xref:service_url>, <xref:or conversation.id>

get_conversation_members

Lists the members of a current conversation.

async get_conversation_members(context: TurnContext)

Parameters

Name	Description
context Required	TurnContext The context object for the turn

Returns

Type	Description
	List of members of the current conversation

Exceptions

Type	Description
TypeError if missing service_url or conversation.id

get_conversations

Lists the Conversations in which this bot has participated for a given channel server.

context.activity.serviceUrl :type service_url: str

async get_conversations(service_url: str, credentials: AppCredentials, continuation_token: str = None)

Parameters

Name	Description
continuation_token	str The continuation token from the previous page of results default value: None
service_url Required
credentials Required

Returns

Type	Description
	A task that represents the work queued to execute

Exceptions

Type	Description
A generic exception error

Remarks

The channel server returns results in pages and each page will include a continuationToken that can be used to fetch the next page of results from the server. If the task completes successfully, the result contains a page of the members of the current conversation. This overload may be called from outside the context of a conversation, as only the bot's service URL and credentials are required.

get_oauth_sign_in_link

Gets the raw sign-in link to be sent to the user for sign-in for a connection name.

async get_oauth_sign_in_link(context: TurnContext, connection_name: str, final_redirect: str = None, oauth_app_credentials: AppCredentials = None) -> str

Parameters

Name	Description
context Required	TurnContext Context for the current turn of conversation with the user
connection_name Required	str Name of the auth connection to use
final_redirect	The final URL that the OAuth flow will redirect to. default value: None
oauth_app_credentials	<xref:botframework.connector.auth.AppCredential> (Optional) AppCredentials for OAuth. default value: None

Returns

Type	Description
	If the task completes successfully, the result contains the raw sign-in link

get_sign_in_resource_from_user

async get_sign_in_resource_from_user(turn_context: TurnContext, connection_name: str, user_id: str, final_redirect: str = None) -> SignInUrlResponse

Parameters

Name	Description
turn_context Required
connection_name Required
user_id Required
final_redirect	default value: None

get_sign_in_resource_from_user_and_credentials

async get_sign_in_resource_from_user_and_credentials(turn_context: TurnContext, oauth_app_credentials: AppCredentials, connection_name: str, user_id: str, final_redirect: str = None) -> SignInUrlResponse

Parameters

Name	Description
turn_context Required
oauth_app_credentials Required
connection_name Required
user_id Required
final_redirect	default value: None

get_token_status

Retrieves the token status for each configured connection for the given user.

Blank will return token status for all configured connections. :type include_filter: str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>

async get_token_status(context: TurnContext, connection_name: str = None, user_id: str = None, include_filter: str = None, oauth_app_credentials: AppCredentials = None) -> List[TokenStatus]

Parameters

Name	Description
context Required
connection_name	default value: None
user_id	default value: None
include_filter	default value: None
oauth_app_credentials	default value: None

Returns

Type	Description
	Array of <xref:botframework.connector.token_api.modelsTokenStatus>

get_user_token

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

:param magic_code" (Optional) user entered code to validate :str magic_code" str :param oauth_app_credentials: (Optional) AppCredentials for OAuth. :type oauth_app_credentials: <xref:botframework.connector.auth.AppCredential>

async get_user_token(context: TurnContext, connection_name: str, magic_code: str = None, oauth_app_credentials: AppCredentials = None) -> TokenResponse

Parameters

Name	Description
context Required
connection_name Required
magic_code	default value: None
oauth_app_credentials	default value: None

Returns

Type	Description
:<xref:class>:’TokenResponse`	Token Response

Exceptions

Type	Description
An exception error

key_for_app_credentials

static key_for_app_credentials(app_id: str, scope: str)

Parameters

Name	Description
app_id Required
scope Required

key_for_connector_client

static key_for_connector_client(service_url: str, app_id: str, scope: str)

Parameters

Name	Description
service_url Required
app_id Required
scope Required

parse_request

Parses and validates request :param req: :return:

async static parse_request(req)

Parameters

Name	Description
req Required

process_activity

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

async process_activity(req, auth_header: str, logic: Callable)

Parameters

Name	Description
req Required	<xref:typing.str> The incoming activity
auth_header Required	<xref:typing.str> The HTTP authentication header of the request
logic Required	Callable The logic to execute at the end of the adapter's middleware pipeline.

Returns

Type	Description
	A task that represents the work queued to execute.

Remarks

This class processes an activity received by the bots web server. This includes any messages sent from a user and is the method that drives what's often referred to as the bots reactive messaging flow. Call this method to reactively send a message to a conversation. If the task completes successfully, then an InvokeResponse is returned; otherwise. null is returned.

process_activity_with_identity

async process_activity_with_identity(activity: Activity, identity: ClaimsIdentity, logic: Callable)

Parameters

Name	Description
activity Required
identity Required
logic Required

process_outgoing_activity

async process_outgoing_activity(turn_context: TurnContext, activity: Activity) -> ResourceResponse

Parameters

Name	Description
turn_context Required
activity Required

send_activities

async send_activities(context: TurnContext, activities: List[Activity]) -> List[ResourceResponse]

Parameters

Name	Description
context Required
activities Required

sign_out_user

Signs the user out with the token server.

async sign_out_user(context: TurnContext, connection_name: str = None, user_id: str = None, oauth_app_credentials: AppCredentials = None)

Parameters

Name	Description
context Required	TurnContext Context for the current turn of conversation with the user
connection_name	str Name of the auth connection to use default value: None
user_id	str User id of user to sign out default value: None
oauth_app_credentials	<xref:botframework.connector.auth.AppCredential> (Optional) AppCredentials for OAuth. default value: None

update_activity

Replaces an activity that was previously sent to a channel. It should be noted that not all channels support this feature.

async update_activity(context: TurnContext, activity: Activity)

Parameters

Name	Description
context Required	The context object for the turn
activity Required	Activity New replacement activity

Returns

Type	Description
	A task that represents the work queued to execute

Exceptions

Type	Description
A generic exception error

Remarks

If the activity is successfully sent, the task result contains a ResourceResponse object containing the ID that the receiving channel assigned to the activity. Before calling this function, set the ID of the replacement activity to the ID of the activity to replace.