App Class

The main Teams application orchestrator.

Manages plugins, tokens, and application lifecycle for Microsoft Teams apps.

Constructor

App(**options: Unpack[AppOptions])

Methods

add_oauth_flow

Register an OAuth connection and return its object.

-[ Notes ]-

Registering a flow turns on per-turn state automatically when the state option was omitted, because connection-less callbacks need somewhere to record which connection a sign-in started on. Pass state=True or a StateOptions to choose the storage yourself, or state=False to opt out — an explicit choice is never overridden. With state off, pending hints fall back to a bounded process-local cache, so a callback handled by another instance cannot be attributed.

Connection-less verify-state callbacks probe hinted flows first, then the remaining registered flows and legacy default connection. Sign-in failures use pending silent-SSO hints for attribution and notify registered flows as a fallback. Token-exchange callbacks carry their connection name and route correctly without state.
event

Decorator to register event handlers with automatic type inference.

Can be used in multiple ways:

  • @app.event (auto-detect from type hints)
  • @app.event("activity")
func

Decorator that registers a function as a remotely callable endpoint.
get_agentic_identity

Get an AgenticIdentity for API calls.

When agentic_app_blueprint_id is omitted, it defaults to the app's own client/app id (self.id).
get_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. For multi-tenant apps, pass a tenant_id to get a tenant-specific token.
get_oauth_flow

Retrieve a previously registered OAuth flow by connection name.
initialize

Initialize the Teams application without starting the HTTP server.

This method sets up credentials, token manager, activity sender, and plugins, allowing you to use app.send() for proactive messaging without running a server.
page

Register a static page to serve at a specific path.

Args: name: Unique name for the page dir_path: Directory containing the static files page_path: Optional path to serve the page at (defaults to /pages/{name})
reply

Send an activity proactively to a conversation, optionally as a threaded reply.

3-arg form reply(conversation_id, message_id, activity): Constructs a threaded conversation ID via to_threaded_conversation_id and sends to that thread. The service determines whether threading is supported for the given conversation type.

2-arg form reply(conversation_id, activity): Sends to the exact conversation ID provided - threaded if it contains ;messageid=, flat otherwise.
send

Send an activity proactively to a conversation.

Sends to the exact conversation ID provided. For channel threads, the conversation ID must include ;messageid= - use to_threaded_conversation_id to construct it, or use reply which handles this automatically.
start

Start the Teams application and begin serving HTTP requests.

This method will block and keep the application running until stopped. This is the main entry point for running your Teams app.
stop

Stop the Teams application.
tab

Add/update a static tab. The tab will be hosted at http://localhost:<PORT>/tabs/<name> or https://<BOT_DOMAIN>/tabs/<name> Scopes default to 'personal'.
use

Add middleware to run on all activities.

add_oauth_flow

Register an OAuth connection and return its object.

-[ Notes ]-

Registering a flow turns on per-turn state automatically when the state option was omitted, because connection-less callbacks need somewhere to record which connection a sign-in started on. Pass state=True or a StateOptions to choose the storage yourself, or state=False to opt out — an explicit choice is never overridden. With state off, pending hints fall back to a bounded process-local cache, so a callback handled by another instance cannot be attributed.

Connection-less verify-state callbacks probe hinted flows first, then the remaining registered flows and legacy default connection. Sign-in failures use pending silent-SSO hints for attribution and notify registered flows as a fallback. Token-exchange callbacks carry their connection name and route correctly without state.

add_oauth_flow(connection_name: str, *, oauth_card_text: str = 'Please Sign In...', sign_in_button_text: str = 'Sign In') -> OAuthFlow

Parameters

Name Description
connection_name
Required

Keyword-Only Parameters

Name Description
oauth_card_text
Default value: Please Sign In...
sign_in_button_text
Default value: Sign In

Exceptions

Type Description
ValueError

if a flow for this connection is already registered (connection names are case-insensitive).

event

Decorator to register event handlers with automatic type inference.

Can be used in multiple ways:

  • @app.event (auto-detect from type hints)
  • @app.event("activity")
event(func_or_event_type: F) -> F

Parameters

Name Description
func_or_event_type

Either the function to decorate or an event type string

Default value: None
event_type
Required

Explicit event type (keyword-only)

Returns

Type Description

Decorated function or decorator

Examples

``<<>>`<<python @app.event async def handle_activity(event: ActivityEvent):

print(f"Activity: {event.activity}")

@app.event("error") async def handle_error(event: ErrorEvent):

print(f"Error: {event.error}")

``<<>>`<<

func

Decorator that registers a function as a remotely callable endpoint.

func(name_or_func: str | FCtx | None = None) -> FCtx | Callable[[FCtx], FCtx]

Parameters

Name Description
name_or_func
Default value: None
str
Required
<xref:<xref:->>

explicit name for the endpoint
Callable
Required
<xref:<xref:->>

directly decorating the function, endpoint name defaults to the function's name

Examples

``<<>>`<<python @app.func async def post_to_chat(ctx: FunctionContext[Any]):

await ctx.send(ctx.data["message"])

``<<>>`<<

get_agentic_identity

Get an AgenticIdentity for API calls.

When agentic_app_blueprint_id is omitted, it defaults to the app's own client/app id (self.id).

get_agentic_identity(agentic_app_id: str | None = None, agentic_user_id: str | None = None, *, tenant_id: str | None = None, agentic_app_blueprint_id: str | None = None) -> AgenticIdentity

Parameters

Name Description
agentic_app_id
Default value: None
agentic_user_id
Default value: None

Keyword-Only Parameters

Name Description
tenant_id
Default value: None
agentic_app_blueprint_id
Default value: None

get_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. For multi-tenant apps, pass a tenant_id to get a tenant-specific token.

get_app_graph(tenant_id: str | None = None) -> GraphServiceClient

Parameters

Name Description
tenant_id

Optional tenant ID. If not provided, uses the app's default tenant.

Default value: None

Exceptions

Type Description
ImportError

If the graph dependencies are not installed.

get_oauth_flow

Retrieve a previously registered OAuth flow by connection name.

get_oauth_flow(connection_name: str) -> OAuthFlow

Parameters

Name Description
connection_name
Required

The OAuth connection name (case-insensitive).

Returns

Type Description

The registered OAuthFlow.

Exceptions

Type Description
ValueError

if no flow is registered for this connection.

initialize

Initialize the Teams application without starting the HTTP server.

This method sets up credentials, token manager, activity sender, and plugins, allowing you to use app.send() for proactive messaging without running a server.

async initialize() -> None

page

Register a static page to serve at a specific path.

Args: name: Unique name for the page dir_path: Directory containing the static files page_path: Optional path to serve the page at (defaults to /pages/{name})

page(name: str, dir_path: str, page_path: str | None = None) -> None

Parameters

Name Description
name
Required
dir_path
Required
page_path
Default value: None

Examples

python app.page("customform", os.path.join(os.path.dirname(__file__), "views", "customform"), "/tabs/dialog-form")

reply

Send an activity proactively to a conversation, optionally as a threaded reply.

3-arg form reply(conversation_id, message_id, activity): Constructs a threaded conversation ID via to_threaded_conversation_id and sends to that thread. The service determines whether threading is supported for the given conversation type.

2-arg form reply(conversation_id, activity): Sends to the exact conversation ID provided - threaded if it contains ;messageid=, flat otherwise.

async reply(conversation_id: str, message_id: str, activity: str | ActivityParams | AdaptiveCard, *, service_url: str | None = None, agentic_identity: AgenticIdentity | None = None) -> SentActivity

Parameters

Name Description
conversation_id
Required

The conversation ID
message_id
Required

The thread root message ID (3-arg form) or the activity (2-arg form)
activity

The activity to send (only in 3-arg form)

Default value: None

Keyword-Only Parameters

Name Description
service_url
Default value: None
agentic_identity
Default value: None

send

Send an activity proactively to a conversation.

Sends to the exact conversation ID provided. For channel threads, the conversation ID must include ;messageid= - use to_threaded_conversation_id to construct it, or use reply which handles this automatically.

async send(conversation_id: str, activity: str | MessageActivityInput | MessageReactionActivityInput | TypingActivityInput | AdaptiveCard, *, service_url: str | None = None, agentic_identity: AgenticIdentity | None = None) -> SentActivity

Parameters

Name Description
conversation_id
Required
activity
Required

Keyword-Only Parameters

Name Description
service_url
Default value: None
agentic_identity
Default value: None

start

Start the Teams application and begin serving HTTP requests.

This method will block and keep the application running until stopped. This is the main entry point for running your Teams app.

async start(port: int | None = None) -> None

Parameters

Name Description
port

Port to listen on (defaults to PORT env var or 3978)

Default value: None

stop

Stop the Teams application.

async stop() -> None

tab

Add/update a static tab. The tab will be hosted at http://localhost:<PORT>/tabs/<name> or https://<BOT_DOMAIN>/tabs/<name> Scopes default to 'personal'.

tab(name: str, path: str) -> None

Parameters

Name Description
displays.
Required
<xref:<xref:name A unique identifier for the entity which the tab>>
content
Required
<xref:<xref:path The path to the directory containing the tab's>>
name
Required
path
Required

use

Add middleware to run on all activities.

use(middleware: Callable[[ActivityContext[Activity]], Awaitable[None]]) -> None

Parameters

Name Description
middleware
Required

Attributes

events

The event emitter instance used by the app.

id

The app's ID from credentials.

port

Port the app is running on.

router

The activity router instance.

token_provider

Token source for resources the SDK does not call automatically.