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 SpecView on GitHubMicrosoft TeamsChatCollaborationCommunicationsMicrosoft 365ProductivityVideo ConferencingAsyncAPIEventsWebhooks
Channels
graph/teams/getAllMessages
subscribereceiveTenantChannelMessages
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
subscribereceiveTenantChatMessages
All chat messages across the tenant
Subscribe to chat messages across all chats in the tenant. Resource path: `/chats/getAllMessages`.
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
subscribereceiveChatMessages
Messages in a specific chat
Subscribe to messages in a specific chat. Resource path: `/chats/{chat-id}/messages`.
graph/users/{userId}/chats/getAllMessages
subscribereceiveUserChatMessages
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`.
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
subscribereceiveTenantChannelChanges
Channel resource changes across the tenant
Subscribe to changes to channels across all teams. Resource path: `/teams/getAllChannels`.
graph/teams/{teamId}/channels
subscribereceiveTeamChannelChanges
Channel resource changes within a specific team
Subscribe to channel changes within a specific team. Resource path: `/teams/{id}/channels`.
graph/chats
subscribereceiveTenantChatChanges
Chat resource changes across the tenant
Subscribe to changes to any chat in the tenant. Resource path: `/chats`.
graph/chats/{chatId}
subscribereceiveChatChanges
Changes to a specific chat resource
Subscribe to changes to a specific chat. Resource path: `/chats/{id}`.
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`.
Subscribe to call recordings becoming available across all online meetings in the organization. Resource path: `communications/onlineMeetings/getAllRecordings`.
Subscribe to recordings in meetings where a specific Teams app is installed. Resource path: `appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings`.
graph/communications/adhocCalls/getAllRecordings
subscribereceiveTenantAdhocCallRecordings
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`.
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
subscribereceiveTenantAdhocCallTranscripts
Transcripts for ad hoc calls across the organization
Subscribe to transcripts for all ad hoc calls in the organization. Resource path: `communications/adhocCalls/getAllTranscripts`.
Subscribe to transcripts for a specific ad hoc call. Resource path: `communications/adhocCalls/{adhocCallId}/transcripts`.
graph/users/{userId}/adhocCalls/getAllTranscripts
subscribereceiveUserAdhocCallTranscripts
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
subscribereceiveLifecycleNotifications
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
subscribereceiveValidationRequest
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
subscribereceiveBotActivity
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: 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
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.