Listening To Events
An event is a foundational concept in building agents — it represents something noteworthy happening either on Microsoft Teams or within your application. These events can originate from the user (e.g. installing or uninstalling your app, sending a message, submitting a form), or from your application server (e.g. startup, error in a handler).
The Teams SDK makes it easy to subscribe to these events and respond appropriately. You can register event handlers to take custom actions when specific events occur — such as logging errors, triggering workflows, or sending follow-up messages.
Here are the events that you can start building handlers for:
| Event Name | Description |
|---|---|
start | Triggered when your application starts. Useful for setup or boot-time logging. |
sign_in | Triggered during a sign-in flow via Teams. |
error | Triggered when an unhandled error occurs in your app. Great for diagnostics. |
activity | Triggered for all incoming Teams activities (messages, commands, etc.). |
activity_response | Triggered when your app sends a response to an activity. Useful for logging. |
activity_sent | Triggered when an activity is sent (not necessarily in response). |
Event handler registration uses @app.event("<event_name>") with an async function that receives an event object specific to the event type (e.g., ErrorEvent, ActivityEvent).
Example 1​
We can subscribe to errors that occur in the app.
@app.event("error")
async def handle_error(event: ErrorEvent):
print(f"Error occurred: {event.error}")
# Or alternatively, send it to an observability platform
Example 2​
When a user signs in using OAuth or SSO, use the Graph API to fetch their profile and say hello.
from microsoft_teams.graph import get_graph_client
graph = app.add_oauth_flow("graph")
@graph.on_signin
async def handle_signin(event: SignInEvent):
client = get_graph_client(event.token_response.token)
me = await client.me.get()
await event.activity_ctx.send(f"👋 Hello {me.display_name}")
The app-wide sign_in event fires for every connection. To react to just one, use its flow's @flow.on_signin handler as shown above. See the auth guide.