Microsoft Teams · AsyncAPI Specification

Microsoft Teams Event Surface

Version 1.0.0

AsyncAPI 2.6 description of the asynchronous event surface for Microsoft Teams. Two distinct delivery channels are modeled: 1. Microsoft Graph change notifications - HTTPS webhook deliveries that Microsoft Graph POSTs to a subscriber-owned `notificationUrl` (and an optional `lifecycleNotificationUrl`) when subscribed Teams resources (chats, channels, teams, chat messages, conversation members, call recordings, call transcripts, Teams app installations) change. 2. Bot Framework activities - HTTPS deliveries that the Teams channel of the Azure Bot Service POSTs to the bot's messaging endpoint when a user (or Teams itself) triggers a conversation event (message, conversationUpdate, messageReaction, installationUpdate, invoke, event, typing, messageUpdate, messageDelete). Resource paths, change types, payload shapes, and bot activity event types are taken from the public Microsoft Learn documentation: - https://learn.microsoft.com/en-us/graph/teams-change-notification-in-microsoft-teams-overview - https://learn.microsoft.com/en-us/graph/teams-changenotifications-chatmessage - https://learn.microsoft.com/en-us/graph/change-notifications-lifecycle-events - https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/subscribe-to-conversation-events - https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/conversation-basics - https://learn.microsoft.com/en-us/microsoftteams/platform/resources/bot-v3/bots-notifications No event types, resource paths, or activity names are invented; everything here is grounded in the source documentation.

View Spec View on GitHub Microsoft TeamsChatCollaborationCommunicationsMicrosoft 365ProductivityVideo ConferencingAsyncAPIEventsWebhooks

Channels

graph/teams/getAllMessages
subscribe receiveTenantChannelMessages
All channel messages across the tenant
Subscribe to chat messages across all channels in all teams in the tenant. Resource path: `/teams/getAllMessages`. Supports `includeResourceData: true` with encryption.
graph/chats/getAllMessages
subscribe receiveTenantChatMessages
All chat messages across the tenant
Subscribe to chat messages across all chats in the tenant. Resource path: `/chats/getAllMessages`.
graph/teams/{teamId}/channels/{channelId}/messages
subscribe receiveChannelMessages
Messages and replies in a specific channel
Subscribe to messages and replies in a specific channel. Resource path: `/teams/{team-id}/channels/{channel-id}/messages`. Supports `$search` and `$filter=mentions/...` query parameters.
graph/chats/{chatId}/messages
subscribe receiveChatMessages
Messages in a specific chat
Subscribe to messages in a specific chat. Resource path: `/chats/{chat-id}/messages`.
graph/users/{userId}/chats/getAllMessages
subscribe receiveUserChatMessages
All chat messages for a specific user
Subscribe to chat messages across all chats a particular user is part of. Resource path: `/users/{user-id}/chats/getAllMessages`.
graph/appCatalogs/teamsApps/{teamsAppId}/installedToChats/getAllMessages
subscribe receiveAppInstalledChatMessages
Chat messages in chats where a Teams app is installed
Subscribe to chat messages across all chats in the tenant where a specific Teams app is installed. Resource path: `/appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessages`.
graph/teams/getAllChannels
subscribe receiveTenantChannelChanges
Channel resource changes across the tenant
Subscribe to changes to channels across all teams. Resource path: `/teams/getAllChannels`.
graph/teams/{teamId}/channels
subscribe receiveTeamChannelChanges
Channel resource changes within a specific team
Subscribe to channel changes within a specific team. Resource path: `/teams/{id}/channels`.
graph/chats
subscribe receiveTenantChatChanges
Chat resource changes across the tenant
Subscribe to changes to any chat in the tenant. Resource path: `/chats`.
graph/chats/{chatId}
subscribe receiveChatChanges
Changes to a specific chat resource
Subscribe to changes to a specific chat. Resource path: `/chats/{id}`.
graph/appCatalogs/teamsApps/{teamsAppId}/installedToChats
subscribe receiveAppInstalledChatChanges
Chat changes for chats where a Teams app is installed
Subscribe to chat changes for chats in which a specific Teams app is installed. Resource path: `/appCatalogs/teamsApps/{id}/installedToChats`.
graph/teams
subscribe receiveTenantTeamChanges
Team resource changes across the tenant
Subscribe to changes to any team in the tenant. Resource path: `/teams`.
graph/teams/{teamId}
subscribe receiveTeamChanges
Changes to a specific team resource
Subscribe to changes to a specific team. Resource path: `/teams/{id}`.
graph/teams/{teamId}/members
subscribe receiveTeamMemberChanges
Conversation member changes in a specific team
Subscribe to membership changes in a specific team. Resource path: `/teams/{id}/members`.
graph/chats/{chatId}/members
subscribe receiveChatMemberChanges
Conversation member changes in a specific chat
Subscribe to membership changes in a specific chat. Resource path: `/chats/{id}/members`.
graph/chats/getAllMembers
subscribe receiveAllChatMemberChanges
Conversation member changes across all chats
Subscribe to membership changes in all chats. Resource path: `/chats/getAllMembers`.
graph/teams/{teamId}/channels/getAllMembers
subscribe receiveTeamChannelMemberChanges
Conversation member changes across all channels in a team
Subscribe to membership changes in all channels under a specific team. Resource path: `teams/{id}/channels/getAllMembers`.
graph/teams/getAllChannels/getAllMembers
subscribe receiveTenantChannelMemberChanges
Conversation member changes across all channels in the tenant
Subscribe to membership changes in all channels across the tenant. Resource path: `teams/getAllChannels/getAllMembers`.
graph/appCatalogs/teamsApps/{teamsAppId}/installedToChats/getAllMembers
subscribe receiveAppInstalledChatMemberChanges
Member changes for chats where a Teams app is installed
Subscribe to membership changes for chats in the tenant where a specific Teams app is installed. Resource path: `/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers`.
graph/appCatalogs/teamsApps/{teamsAppId}/installations
subscribe receiveTeamsAppInstallations
Teams app installation lifecycle events
Subscribe to install, upgrade, and delete events for a specific Teams app. Resource path: `/appCatalogs/teamsApps/{teams-app-id}/installations`.
graph/communications/onlineMeetings/getAllRecordings
subscribe receiveTenantOnlineMeetingRecordings
Online meeting recordings across the organization
Subscribe to call recordings becoming available across all online meetings in the organization. Resource path: `communications/onlineMeetings/getAllRecordings`.
graph/communications/onlineMeetings/{onlineMeetingId}/recordings
subscribe receiveOnlineMeetingRecordings
Recordings for a specific online meeting
Subscribe to recordings for a specific online meeting. Resource path: `communications/onlineMeetings/{onlineMeetingId}/recordings`.
graph/users/{userId}/onlineMeetings/getAllRecordings
subscribe receiveUserOnlineMeetingRecordings
Online meeting recordings for a specific organizer
Subscribe to call recordings for meetings organized by a specific user. Resource path: `users/{userId}/onlineMeetings/getAllRecordings`.
graph/appCatalogs/teamsApps/{teamsAppId}/installedToOnlineMeetings/getAllRecordings
subscribe receiveAppInstalledOnlineMeetingRecordings
Meeting recordings where a Teams app is installed
Subscribe to recordings in meetings where a specific Teams app is installed. Resource path: `appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings`.
graph/communications/adhocCalls/getAllRecordings
subscribe receiveTenantAdhocCallRecordings
Recordings for ad hoc calls across the organization
Subscribe to recordings for all ad hoc calls (PSTN, 1:1, group calls) in the organization. Resource path: `communications/adhocCalls/getAllRecordings`.
graph/communications/adhocCalls/{adhocCallId}/recordings
subscribe receiveAdhocCallRecordings
Recordings for a specific ad hoc call
Subscribe to recordings for a specific ad hoc call. Resource path: `communications/adhocCalls/{adhocCallId}/recordings`.
graph/users/{userId}/adhocCalls/getAllRecordings
subscribe receiveUserAdhocCallRecordings
Recordings for ad hoc calls initiated by a user
Subscribe to recordings for ad hoc calls initiated by a specific user. Resource path: `users/{userId}/adhocCalls/getAllRecordings`.
graph/communications/onlineMeetings/getAllTranscripts
subscribe receiveTenantOnlineMeetingTranscripts
Online meeting transcripts across the organization
Subscribe to call transcripts for all online meetings in the organization. Resource path: `communications/onlineMeetings/getAllTranscripts`.
graph/communications/onlineMeetings/{onlineMeetingId}/transcripts
subscribe receiveOnlineMeetingTranscripts
Transcripts for a specific online meeting
Subscribe to transcripts for a specific online meeting. Resource path: `communications/onlineMeetings/{onlineMeetingId}/transcripts`.
graph/users/{userId}/onlineMeetings/getAllTranscripts
subscribe receiveUserOnlineMeetingTranscripts
Online meeting transcripts for a specific organizer
Subscribe to transcripts for meetings organized by a specific user. Resource path: `users/{userId}/onlineMeetings/getAllTranscripts`.
graph/appCatalogs/teamsApps/{teamsAppId}/installedToOnlineMeetings/getAllTrancripts
subscribe receiveAppInstalledOnlineMeetingTranscripts
Meeting transcripts where a Teams app is installed
Subscribe to transcripts in meetings where a specific Teams app is installed. Resource path: `appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts` (note the spelling used by the documentation).
graph/communications/adhocCalls/getAllTranscripts
subscribe receiveTenantAdhocCallTranscripts
Transcripts for ad hoc calls across the organization
Subscribe to transcripts for all ad hoc calls in the organization. Resource path: `communications/adhocCalls/getAllTranscripts`.
graph/communications/adhocCalls/{adhocCallId}/transcripts
subscribe receiveAdhocCallTranscripts
Transcripts for a specific ad hoc call
Subscribe to transcripts for a specific ad hoc call. Resource path: `communications/adhocCalls/{adhocCallId}/transcripts`.
graph/users/{userId}/adhocCalls/getAllTranscripts
subscribe receiveUserAdhocCallTranscripts
Transcripts for ad hoc calls initiated by a user
Subscribe to transcripts for ad hoc calls initiated by a specific user. Resource path: `users/{userId}/adhocCalls/getAllTranscripts`.
graph/lifecycle
subscribe receiveLifecycleNotifications
Subscription lifecycle notifications
Deliveries to the `lifecycleNotificationUrl` for any Teams subscription. Lifecycle notifications signal subscription state changes (`reauthorizationRequired`, `subscriptionRemoved`, `missed`) and contain no resource data.
graph/validation
subscribe receiveValidationRequest
Subscription endpoint validation handshake
Graph validation handshake. When a subscription is created or updated, Microsoft Graph sends a `POST` with `validationToken` query parameter that the endpoint must echo back as text/plain within 10 seconds.
bot/activities
subscribe receiveBotActivity
Bot Framework Activity delivered to the bot endpoint
The Teams channel of the Azure Bot Service POSTs Bot Framework Activity objects to the bot's messaging endpoint. The `type` discriminator identifies the kind of activity; for `conversationUpdate` and `event` activities, the `channelData.eventType` discriminator further identifies Teams-specific sub-events.

Messages

✉
ChatMessageNotification
chatMessage change notification
Notification payload for changes on the chatMessage resource. The resource may be in a channel or chat context. When `includeResourceData` is true on the subscription, `encryptedContent` carries the AES-encrypted chatMessage payload.
✉
ChannelNotification
channel change notification
✉
ChatNotification
chat change notification
✉
TeamNotification
team change notification
✉
ConversationMemberNotification
conversationMember change notification
✉
TeamsAppInstallationNotification
teamsAppInstallation change notification
✉
CallRecordingNotification
callRecording change notification
✉
CallTranscriptNotification
callTranscript change notification
✉
LifecycleNotification
Subscription lifecycle notification
Subscription lifecycle event. The `lifecycleEvent` value is one of `reauthorizationRequired`, `subscriptionRemoved`, or `missed`. Subscribers must respond with HTTP 202 within 30 seconds.
✉
ValidationRequest
Subscription endpoint validation request
Sent by Microsoft Graph with the `validationToken` query parameter when a subscription is created or updated. The endpoint must respond within 10 seconds with HTTP 200 and `text/plain` body equal to the URL-decoded `validationToken`.
✉
MessageActivity
Bot Framework message activity
✉
MessageUpdateActivity
Bot Framework messageUpdate activity
Sent when a previously sent message is edited or restored from soft-delete. `channelData.eventType` is `editMessage` or `undeleteMessage`.
✉
MessageDeleteActivity
Bot Framework messageDelete activity
Sent when a message is soft-deleted. `channelData.eventType` is `softDeleteMessage`.
✉
ConversationUpdateActivity
Bot Framework conversationUpdate activity
Sent for membership and team/channel lifecycle changes. The `channelData.eventType` discriminator identifies the Teams-specific sub-event: `teamMemberAdded`, `teamMemberRemoved`, `teamRenamed`, `channelCreated`, `channelRenamed`, `channelDeleted`, `channelRestored`, `teamArchived`, `teamUnarchived`, `teamDeleted`, `teamHardDeleted`, `teamRestored`.
✉
MessageReactionActivity
Bot Framework messageReaction activity
Sent when a user adds or removes a reaction (like, heart, laugh, surprised, sad, angry, and other supported emoji reactions) to a message previously sent by the bot.
✉
InstallationUpdateActivity
Bot Framework installationUpdate activity
Sent when the bot is installed, uninstalled, or upgraded in a conversation thread. The `action` field is one of `add`, `remove`, `add-upgrade`, or `remove-upgrade`.
✉
TypingActivity
Bot Framework typing activity
✉
InvokeActivity
Bot Framework invoke activity
Synchronous request from Teams that expects a response payload. The `name` discriminator identifies the invoke kind. Documented Teams invoke names include `composeExtension/query`, `composeExtension/queryLink`, `composeExtension/selectItem`, `composeExtension/submitAction`, `composeExtension/fetchTask`, `composeExtension/setting`, `composeExtension/onCardButtonClicked`, `composeExtension/anonymousQueryLink`, `task/fetch`, `task/submit`, `tab/fetch`, `tab/submit`, `adaptiveCard/action`, `message/submitAction`, `messageBack`, `signin/verifyState`, `signin/tokenExchange`, `fileConsent/invoke`, `actionableMessage/executeAction`, `handoff/action`, and `config/fetch`, `config/submit`.
✉
EventActivity
Bot Framework event activity
Asynchronous notification from Teams. Documented Teams event names include `application/vnd.microsoft.readReceipt`, `application/vnd.microsoft.meetingStart`, `application/vnd.microsoft.meetingEnd`, `application/vnd.microsoft.meetingParticipantJoin`, `application/vnd.microsoft.meetingParticipantLeave`, and `application/vnd.microsoft.botMessagePreview`.

Servers

https
subscriberWebhook {notificationUrl}
Subscriber-owned HTTPS endpoint registered as `notificationUrl` (and optionally `lifecycleNotificationUrl`) on a Microsoft Graph subscription. Microsoft Graph POSTs change notification batches to this URL.
https
botMessagingEndpoint {botEndpoint}
Bot messaging endpoint registered with the Azure Bot Service. The Teams channel POSTs Bot Framework Activity objects to this URL.

AsyncAPI Specification

Raw ↑
asyncapi: 2.6.0
info:
  title: Microsoft Teams Event Surface
  version: 1.0.0
  description: "AsyncAPI 2.6 description of the asynchronous event surface for Microsoft\nTeams. Two distinct delivery channels\
    \ are modeled:\n\n  1. Microsoft Graph change notifications - HTTPS webhook deliveries that\n     Microsoft Graph POSTs\
    \ to a subscriber-owned `notificationUrl` (and an\n     optional `lifecycleNotificationUrl`) when subscribed Teams resources\n\
    \     (chats, channels, teams, chat messages, conversation members, call\n     recordings, call transcripts, Teams app\
    \ installations) change.\n  2. Bot Framework activities - HTTPS deliveries that the Teams channel of\n     the Azure Bot\
    \ Service POSTs to the bot's messaging endpoint when a\n     user (or Teams itself) triggers a conversation event (message,\n\
    \     conversationUpdate, messageReaction, installationUpdate, invoke,\n     event, typing, messageUpdate, messageDelete).\n\
    \nResource paths, change types, payload shapes, and bot activity event types\nare taken from the public Microsoft Learn\
    \ documentation:\n\n  - https://learn.microsoft.com/en-us/graph/teams-change-notification-in-microsoft-teams-overview\n\
    \  - https://learn.microsoft.com/en-us/graph/teams-changenotifications-chatmessage\n  - https://learn.microsoft.com/en-us/graph/change-notifications-lifecycle-events\n\
    \  - https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/subscribe-to-conversation-events\n\
    \  - https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/conversation-basics\n  - https://learn.microsoft.com/en-us/microsoftteams/platform/resources/bot-v3/bots-notifications\n\
    \nNo event types, resource paths, or activity names are invented; everything\nhere is grounded in the source documentation.\n"
  contact:
    name: Microsoft Graph / Microsoft Teams Platform
    url: https://learn.microsoft.com/en-us/graph/teams-concept-overview
  license:
    name: Microsoft Learn Terms of Use
    url: https://learn.microsoft.com/en-us/legal/termsofuse
  x-externalDocs:
    description: Change notifications for Microsoft Teams resources
    url: https://learn.microsoft.com/en-us/graph/teams-change-notification-in-microsoft-teams-overview
  x-tags:
  - name: microsoft-graph
  - name: change-notifications
  - name: webhooks
  - name: bot-framework


# --- truncated at 32 KB (50 KB total) ---
# Full source: https://artifacts.apis.io/microsoft-teams/asyncapi/microsoft-teams-asyncapi.yaml

Work with this as data

Every AsyncAPI spec here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for asyncapi

4 MCP tools reach this
  • find_asyncapisBrowse and filter every AsyncAPI spec in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This AsyncAPI spec
curl "https://apis.io/api/v1/asyncapis/microsoft-teams-asyncapi"
All asyncapi
curl "https://apis.io/api/v1/asyncapis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.