Edit

Share via

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

alt-text for on-event-1.png

alt-text for on-event-2.png

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.
signin Triggered during a sign-in flow via Teams.
error Triggered when an unhandled error occurs in your app. Great for diagnostics.
activity A catch-all for 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 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).

Note

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.OnError((sender, @event) =>
{
    // do something with the error
    app.Logger.Info(@event.Exception.ToString());
});

@app.event("error")
async def handle_error(event: ErrorEvent):
    """Handle error events."""
    print(f"Error occurred: {event.error}")
    if hasattr(event, "context") and event.context:
        print(f"Context: {event.context}")

app.event('error', ({ error }) => {
  app.log.error(error);
  // Or Alternatively, send it to an observability platform
});

Example 2

When an activity is received, log its JSON payload.

app.OnActivity((sender, @event) =>
{
    app.Logger.Info(@event.Activity.ToString());
});

When an activity is received, log its payload.

@app.event("activity")
async def handle_activity(event: ActivityEvent):
    """Handle activity events."""
    print(f"Activity received: {event.activity}")

When a user signs in using OAuth or SSO, use the graph api to fetch their profile and say hello.

import * as endpoints from '@microsoft/teams.graph-endpoints';

app.event('signin', async ({ activity, send, userGraph }) => {
  const me = await userGraph.call(endpoints.me.get);
  await send(`👋 Hello ${me.name}`);
});
  • Last updated on