ActivityContext Class

Context object passed to activity handlers with middleware support.

Note

The single-connection OAuth surface here - <xref:is_signed_in>,

<xref:user_token>, user_graph, sign_in,

sign_out and get_user_token - predates

multi-connection support and is deprecated.

Register connections with

app.add_oauth_flow(name) and use the returned OAuthFlow, which

pins every operation to the connection that owns it.

Constructor

ActivityContext(activity: T, app_id: str, storage: Storage[str, Any], api: ApiClient, user_token: str | None, conversation_ref: ConversationReference, is_signed_in: bool, connection_name: str, app_token: str | StringLike | Callable[[], str | StringLike | None | Awaitable[str | StringLike | None]] | None, cloud: CloudEnvironment = CloudEnvironment(login_endpoint='https://login.microsoftonline.com', login_tenant='botframework.com', bot_scope='https://api.botframework.com/.default', agent_bot_scope='https://botapi.skype.com/.default', token_service_url='https://token.botframework.com', openid_metadata_url='https://login.botframework.com/v1/.well-known/openidconfiguration', token_issuer='https://api.botframework.com', graph_scope='https://graph.microsoft.com/.default'), oauth_connection_names: Sequence[str] | None = None, files_credential: GraphCredential | None = None)

Parameters

Name	Description
activity Required
app_id Required
storage Required
api Required
user_token Required
conversation_ref Required
is_signed_in Required
connection_name Required
app_token Required
cloud	Default value: CloudEnvironment(login_endpoint='https://login.microsoftonline.com', login_tenant='botframework.com', bot_scope='https://api.botframework.com/.default', agent_bot_scope='https://botapi.skype.com/.default', token_service_url='https://token.botframework.com', openid_metadata_url='https://login.botframework.com/v1/.well-known/openidconfiguration', token_issuer='https://api.botframework.com', graph_scope='https://graph.microsoft.com/.default')
oauth_connection_names	Default value: None
files_credential	Default value: None

Methods

get_connection_status	Get the token status for every OAuth connection registered on the bot. A single Token Service call returns the status for all connections, so the developer never needs to enumerate connection names manually. Service failures propagate rather than being reported as signed out. The bulk call reports only connections the Token Service knows about, and it can lag a token that was just written. Any registered OAuth flow that comes back missing or has_token=False is therefore re-checked with a direct per-connection lookup, so a freshly signed-in flow is never reported as signed out. Connections that are not registered are passed through untouched, and a non-404 lookup failure propagates.
get_user_token	Get the user's token for a connection. Deprecated since version Use: app.get_oauth_flow(name).get_token(ctx), which reads the token from the flow that owns the connection.
next	Call the next middleware in the chain.
quote	Send a message to the conversation with a quoted message reference prepended to the text. Teams renders the quoted message as a preview bubble above the response text.
reply	Send a message in the current conversation with a visual quote of the inbound message. In channels, sends to the current thread with a quoted reply. In other scopes, sends with a quoted reply. To send without quoting, use send.
send	Send a message in the current conversation without quoting. In channels, sends to the current thread. In scopes that do not support threading (group chat, meetings), sends as a normal message. To send with a visual quote of the inbound message, use reply.
set_next	Set the next handler in the middleware chain.
sign_in	Initiate a sign-in flow for the user. Deprecated since version Targets: the app's single connection_name, which does not generalize past one connection. Use app.get_oauth_flow(name).sign_in(ctx, options), which pins the connection to the flow that owns it.
sign_out	Sign out the user by clearing their token. This method will remove the user's token from the storage. Deprecated since version Use: app.get_oauth_flow(name).sign_out(ctx), which cannot sign out of the wrong connection.

get_connection_status

Get the token status for every OAuth connection registered on the bot.

A single Token Service call returns the status for all connections, so the developer never needs to enumerate connection names manually. Service failures propagate rather than being reported as signed out.

The bulk call reports only connections the Token Service knows about, and it can lag a token that was just written. Any registered OAuth flow that comes back missing or has_token=False is therefore re-checked with a direct per-connection lookup, so a freshly signed-in flow is never reported as signed out. Connections that are not registered are passed through untouched, and a non-404 lookup failure propagates.

async get_connection_status() -> List[TokenStatus]

get_user_token

Get the user's token for a connection.

Deprecated since version Use: app.get_oauth_flow(name).get_token(ctx), which reads the token from the flow that owns the connection.

async get_user_token(connection_name: str | None = None) -> str | None

Parameters

Name	Description
connection_name	The connection to read. Defaults to the app's default connection. Default value: None

Returns

Type	Description
	The token if the user is signed in, or None if they are not (the Token Service returns 404 when no token is cached).

Exceptions

Type	Description
HTTPStatusError	for any non-404 failure (e.g. the Token Service is unavailable). Such errors are surfaced rather than being masked as "not signed in", so a genuine outage is not mistaken for a logged-out user.

next

Call the next middleware in the chain.

async next() -> None

quote

Send a message to the conversation with a quoted message reference prepended to the text. Teams renders the quoted message as a preview bubble above the response text.

async quote(message_id: str, input: str | MessageActivityInput | MessageReactionActivityInput | TypingActivityInput) -> SentActivity

Parameters

Name	Description
message_id Required	The ID of the message to quote
input Required	The response text or activity — a quote placeholder for message_id will be prepended to its text

Returns

Type	Description
	The sent activity

reply

Send a message in the current conversation with a visual quote of the inbound message.

In channels, sends to the current thread with a quoted reply. In other scopes, sends with a quoted reply. To send without quoting, use send.

async reply(input: str | MessageActivityInput | MessageReactionActivityInput | TypingActivityInput) -> SentActivity

Parameters

Name	Description
input Required

send

Send a message in the current conversation without quoting.

In channels, sends to the current thread. In scopes that do not support threading (group chat, meetings), sends as a normal message. To send with a visual quote of the inbound message, use reply.

async send(message: str | MessageActivityInput | MessageReactionActivityInput | TypingActivityInput | AdaptiveCard, conversation_ref: ConversationReference | None = None) -> SentActivity

Parameters

Name	Description
message Required	The message to send, can be a string, ActivityParams, or AdaptiveCard
conversation_ref	Optional conversation reference to send to a different conversation or thread Default value: None

set_next

Set the next handler in the middleware chain.

set_next(handler: Callable[[], Awaitable[None]]) -> None

Parameters

Name	Description
handler Required

sign_in

Initiate a sign-in flow for the user.

Deprecated since version Targets: the app's single connection_name, which does not generalize past one connection. Use app.get_oauth_flow(name).sign_in(ctx, options), which pins the connection to the flow that owns it.

async sign_in(options: SignInOptions | None = None) -> str | None

Parameters

Name	Description
options	Optional signin options to customize the flow Default value: None

Returns

Type	Description
	The token if already available, otherwise None after sending OAuth card

sign_out

Sign out the user by clearing their token.

This method will remove the user's token from the storage.

Deprecated since version Use: app.get_oauth_flow(name).sign_out(ctx), which cannot sign out of the wrong connection.

async sign_out(connection_name: str | None = None) -> None

Parameters

Name	Description
connection_name	The connection to sign out of. Defaults to the app's default connection. Default value: None

Exceptions

Type	Description
HTTPStatusError	if the Token Service rejects the request. A failed sign-out leaves the token in place, so callers must be able to see that it did not happen.

Attributes

app_graph

Get a Microsoft Graph client configured with the app's token.

This client can be used for app-only operations that don't require user context.

Exceptions

Type	Description
ValueError	If no app token is available.
RuntimeError	If the graph client cannot be created.
ImportError	If the graph dependencies are not installed.

files

file.download.info` subset of activity.attachments, mapped to IncomingFile. See FilesAccessor.

stream

user_graph

Get a Microsoft Graph client configured with the user's token.

Deprecated since version Built: from <xref:user_token>, which holds the token for whichever connection signed in most recently rather than the one that talks to Microsoft Graph.

Read the token from the owning flow instead:: token = await app.get_oauth_flow("graph").get_token(ctx)

Exceptions

Type	Description
ValueError	If the user is not signed in or doesn't have a valid token.
RuntimeError	If the graph client cannot be created.
ImportError	If the graph dependencies are not installed.