Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.
To identify the resources for which you can create subscriptions and the limitations on subscriptions, see Set up notifications for changes in resource data: Supported resources.
Some resources support rich notifications, that is, notifications that include resource data. For more information about these resources, see Set up change notifications that include resource data: Supported resources.
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Creating a subscription requires read permission to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permissions.
Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including taking caution before choosing the permissions, search for the following permissions in Permissions.
Note
Supported resource | Delegated (work or school account) | Delegated (personal Microsoft account) | Application |
---|---|---|---|
aiInteraction copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions Copilot AI interactions that a particular user is part of. |
AiEnterpriseInteraction.Read | Not supported. | AiEnterpriseInteraction.Read.All, AiEnterpriseInteraction.Read.User |
aiInteraction copilot/interactionHistory/getAllEnterpriseInteractions Copilot AI interactions in an organization. |
Not supported. | Not supported. | AiEnterpriseInteraction.Read.All |
approvalItems | Not supported. | Not supported. | ApprovalSolution.ReadWrite.All |
callRecord | Not supported. | Not supported. | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings Any recording becomes available in the tenant. |
Not supported. | Not supported. | OnlineMeetingRecording.Read.All |
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings Any recording becomes available for a specific meeting. |
OnlineMeetingRecording.Read.All | Not supported. | OnlineMeetingRecording.Read.All |
callRecording users/{userId}/onlineMeetings/getAllRecordings A call recording that becomes available in a meeting organized by a specific user. |
OnlineMeetingRecording.Read.All | Not supported. | OnlineMeetingRecording.Read.All |
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings A call recording that becomes available in a meeting where a particular Teams app is installed. |
Not supported. | Not supported. | OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.Chat |
callTranscript communications/onlineMeetings/getAllTranscripts Any transcript becomes available in the tenant. |
Not supported. | Not supported. | OnlineMeetingTranscript.Read.All |
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts Any transcript becomes available for a specific meeting. |
OnlineMeetingTranscript.Read.All | Not supported. | OnlineMeetingTranscript.Read.All |
callTranscript users/{userId}/onlineMeetings/getAllTranscripts A call transcript that becomes available in a meeting organized by a specific user. |
OnlineMeetingTranscript.Read.All | Not supported. | OnlineMeetingTranscript.Read.All |
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts A call transcript that becomes available in a meeting where a particular Teams app is installed. |
Not supported. | Not supported. | OnlineMeetingTranscript.Read.All, OnlineMeetingTranscript.Read.Chat |
channel /teams/getAllChannels All channels in an organization. |
Not supported. | Not supported. | Channel.ReadBasic.All, ChannelSettings.Read.All |
channel /teams/{id}/channels All channels in a particular team in an organization. |
Channel.ReadBasic.All, ChannelSettings.Read.All | Not supported. | Channel.ReadBasic.All, ChannelSettings.Read.All |
chat /chats All chats in an organization. |
Not supported. | Not supported. | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
chat /chats/{id} A particular chat. |
Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Not supported. | ChatSettings.Read.Chat, ChatSettings.ReadWrite.Chat, Chat.Manage.Chat, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
chat /appCatalogs/teamsApps/{id}/installedToChats All chats in an organization where a particular Teams app is installed. |
Not supported. | Not supported. | Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
chat /users/{id}/chats All chats that a particular user is part of. |
Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Not supported. | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
chatMessage /teams/{id}/channels/{id}/messages All messages and replies in a particular channel. |
ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All | Not supported. | ChannelMessage.Read.Group, ChannelMessage.Read.All |
chatMessage /teams/getAllMessages All channel messages in organization. |
Not supported. | Not supported. | ChannelMessage.Read.All |
chatMessage /chats/{id}/messages All messages in a chat. |
Chat.Read, Chat.ReadWrite | Not supported. | Chat.Read.All |
chatMessage /chats/getAllMessages All chat messages in an organization. |
Not supported. | Not supported. | Chat.Read.All |
chatMessage /users/{id}/chats/getAllMessages Chat messages for all chats a particular user is part of. |
Chat.Read, Chat.ReadWrite | Not supported. | Chat.Read.All, Chat.ReadWrite.All |
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages Chat messages for all chats in an organization where a particular Teams app is installed. |
Not supported. | Not supported. | Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
contact | Contacts.Read | Contacts.Read | Contacts.Read |
conversationMember /chats/getAllMembers Members of all chats in an organization. |
Not supported. | Not supported. | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
conversationMember /chats/{id}/members Members of a particular chat. |
ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Not supported. | ChatMember.Read.Chat, Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
conversationMember /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Chat members for all chats in an organization where a particular Teams app is installed. |
Not supported. | Not supported. | ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
conversationMember /teams/getAllMembers Members in all teams in an organization. |
Not supported. | Not supported. | TeamMember.Read.All, TeamMember.ReadWrite.All |
conversationMember /teams/{id}/members Members in a particular team. |
TeamMember.Read.All | Not supported. | TeamMember.Read.All |
conversationMember /teams/{id}/channels/getAllMembers Members in all private channels of a particular team. |
Not supported. | Not supported. | ChannelMember.Read.All |
conversationMember /teams/getAllChannels/getAllMembers |
Not supported. | Not supported. | ChannelMember.Read.All |
driveItem (user's personal OneDrive) | Not supported. | Files.ReadWrite | Not supported. |
driveItem (OneDrive for work or school) | Files.ReadWrite.All | Not supported. | Files.ReadWrite.All |
event | Calendars.Read | Calendars.Read | Calendars.Read |
group | Group.Read.All | Not supported. | Group.Read.All |
group conversation | Group.Read.All | Not supported. | Not supported. |
list | Sites.ReadWrite.All | Not supported. | Sites.ReadWrite.All |
message | Mail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.Read | Mail.Read |
offerShiftRequest /teams/{id}/schedule/offerShiftRequests Changes to any offer shift request in a team. |
Schedule.Read.All, Schedule.ReadWrite.All | Not supported. | Schedule.Read.All, Schedule.ReadWrite.All |
onlineMeeting | Not supported. | Not supported. | OnlineMeetings.Read.All, OnlineMeetings.ReadWrite.All |
openShiftChangeRequest /teams/{id}/schedule/openShiftChangeRequests Changes to any open shift request in a team. |
Schedule.Read.All, Schedule.ReadWrite.All | Not supported. | Schedule.Read.All, Schedule.ReadWrite.All |
presence | Presence.Read.All | Not supported. | Not supported. |
printer | Not supported. | Not supported. | Printer.Read.All, Printer.ReadWrite.All |
printTaskDefinition | Not supported. | Not supported. | PrintTaskDefinition.ReadWrite.All |
security alert | SecurityEvents.ReadWrite.All | Not supported. | SecurityEvents.ReadWrite.All |
shift /teams/{id}/schedule/shifts Changes to any shift in a team. |
Schedule.Read.All, Schedule.ReadWrite.All | Not supported. | Schedule.Read.All, Schedule.ReadWrite.All |
swapShiftsChangeRequest /teams/{id}/schedule/swapShiftsChangeRequests Changes to any swap shift request in a team. |
Schedule.Read.All, Schedule.ReadWrite.All | Not supported. | Schedule.Read.All, Schedule.ReadWrite.All |
team /teams All teams in an organization. |
Not supported. | Not supported. | Team.ReadBasic.All, TeamSettings.Read.All |
team /teams/{id} A particular team. |
Team.ReadBasic.All, TeamSettings.Read.All | Not supported. | Team.ReadBasic.All, TeamSettings.Read.All |
timeOffRequest /teams/{id}/schedule/timeOffRequests Changes to any time off request in a team. |
Schedule.Read.All, Schedule.ReadWrite.All | Not supported. | Schedule.Read.All, Schedule.ReadWrite.All |
todoTask | Tasks.ReadWrite | Tasks.ReadWrite | Not supported. |
user | User.Read.All | User.Read.All | User.Read.All |
virtualEventWebinar | VirtualEvent.Read | Not supported. | VirtualEvent.Read.All |
baseTask (deprecated) | Tasks.ReadWrite | Tasks.ReadWrite | Not supported. |
Note
The following permissions use resource-specific consent:
chatMessage subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true
), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified for such subscriptions.
Use the Prefer: include-unknown-enum-members
request header to get the following values in chatMessage messageType evolvable enum: systemEventMessage
for /teams/{id}/channels/{id}/messages
and /chats/{id}/messages
resource.
Note
/teams/getAllMessages
, /chats/getAllMessages
, /me/chats/getAllMessages
, /users/{id}/chats/getAllMessages
, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
are metered APIs; payment models and licensing requirements may apply.
/teams/getAllMessages
and /chats/getAllMessages
support both model=A
and model=B
payment models,
/me/chats/getAllMessages
, /users/{id}/chats/getAllMessages
, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
support only model=B
.
If you don't specify a payment model in your query, the default evaluation mode will be used.
Note
To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.
conversationMember subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true
), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified.
Note
/teams/getAllMembers
, /chats/getAllMembers
, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
are metered APIs; payment models and licensing requirements may apply.
/teams/getAllMembers
and /chats/getAllMembers
support both model=A
and model=B
payment models. /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
supports only model=B
.
If you don't specify a payment model in your query, the default evaluation mode will be used.
Note
To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.
team, channel, and chat subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true
), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified.
You can use the notifyOnUserSpecificProperties query string parameter when you subscribe to changes in a particular chat or at user level. When you set the query string parameter notifyOnUserSpecificProperties to true
during subscription creation, two types of payloads are sent to the subscriber. One type contains user-specific properties, and the other is sent without them. For more information, see Get change notifications for chats using Microsoft Graph.
Note
/appCatalogs/teamsApps/{id}/installedToChats
has licensing and payment requirements, specifically supporting only model=B
.
If no model is specified, evaluation mode will be used.
Note
To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.
Specify the model
query parameter in the resource property in the request body.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "chats/getAllMessages?model=A",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
Subscriptions on Copilot AI interactions require a valid Copilot license that includes the following Copilot service plans:
For subscriptions that target Copilot AI interactions that a particular user is part of, the user in the resource path must have the previous service plans assigned to them in a valid state.
For subscriptions that target Copilot AI interactions for the entire tenant, the tenant must have valid licenses provisioned that include all previous Copilot service plans.
More limitations apply to subscriptions on OneDrive items. The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.
On a personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. On OneDrive for work or school, you can subscribe to only the root folder. Change notifications are sent for the requested changes on the subscribed folder or any file, folder, or other driveItem instances in its hierarchy. You can't subscribe to drive or driveItem instances that aren't folders, such as individual files.
OneDrive for work or school and SharePoint support sending your application notifications of security events that occur on a driveItem. To subscribe to these events, add the prefer:includesecuritywebhooks
header to your request to create a subscription. After the subscription is created, you will receive notifications when the permissions on an item change. This header applies to SharePoint and OneDrive for work or school but not consumer OneDrive accounts.
You can subscribe to changes in Outlook contact, event, or message resources and optionally specify in the POST request payload whether to include encrypted resource data in notifications.
Creating and managing (getting, updating, and deleting) a subscription requires a read scope to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permission. Outlook change notifications support delegated and application permission scopes. Note the following limitations:
Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. For example, you can't use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.
To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:
Subscriptions on onlineMeetings and presence require the encryptionCertificate and encryptionCertificateId property when creating a subscription for notifications with encrypted resource data. For more information, see setting up change notifications to include resource data. For details about online meeting subscriptions, see Get change notifications for online meetings.
Subscriptions on virtual events support only basic notifications and are limited to a few entities of a virtual event. For more information about the supported subscription types, see Get change notifications for Microsoft Teams virtual event updates.
POST /subscriptions
Name | Type | Description |
---|---|---|
Authorization | string | Bearer {token}. Required. Learn more about authentication and authorization. |
In the request body, supply a JSON representation of subscription object.
If successful, this method returns a 201 Created
response code and a subscription object in the response body.
For details about how errors are returned, see Error responses.
In the request body, supply a JSON representation of the subscription object.
The clientState
and latestSupportedTlsVersion
fields are optional.
This request creates a subscription for change notifications about new mail received by the currently signed-in user.
POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "me/mailFolders('Inbox')/messages",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
In the request body, supply a JSON representation of the subscription object.
The clientState
and latestSupportedTlsVersion
fields are optional.
Duplicate subscriptions aren't allowed. When a subscription request contains the same values for changeType and resource that an existing subscription contains, the request fails with an HTTP error code 409 Conflict
, and the error message Subscription Id <> already exists for the requested combination
.
The following are valid values for the resource property.
Resource type | Examples |
---|---|
approvalItems | solution/approval/approvalItems |
callRecord | communications/callRecords |
callRecording | communications/onlineMeetings/getAllRecordings , communications/onlineMeetings/{onlineMeetingId}/recordings , users/{userId}/onlineMeetings/getAllRecordings , appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings |
callTranscript | communications/onlineMeetings/getAllTranscripts , communications/onlineMeetings/{onlineMeetingId}/transcripts , users/{userId}/onlineMeetings/getAllTranscripts , appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts |
channel | /teams/getAllChannels , /teams/{id}/channels |
chat | /chats , /chats/{id} |
chatMessage | chats/{id}/messages , chats/getAllMessages , teams/{id}/channels/{id}/messages , teams/getAllMessages |
contact | me/contacts |
conversationMember | /chats/{id}/members , /chats/getAllMembers , /teams/{id}/members , /teams/getAllMembers , /teams/{id}/channels/getAllMembers |
driveItem | me/drive/root |
event | me/events |
group | groups |
group conversation | groups('{id}')/conversations |
list | sites/{site-id}/lists/{list-id} |
message | me/mailfolders('inbox')/messages , me/messages |
onlineMeeting | /communications/onlineMeetings/?$filter=JoinWebUrl eq '{JoinWebUrl}' |
presence | /communications/presences/{id} (single user), /communications/presences?$filter=id in ('{id}','{id}',…) (multiple users) |
printer | print/printers/{id}/jobs |
printTaskDefinition | print/taskDefinitions/{id}/tasks |
team | /teams , /teams/{id} |
user | users |
todoTask | /me/todo/lists/{todoTaskListId}/tasks |
security alert | security/alerts?$filter=status eq 'NewAlert' |
baseTask (deprecated) | /me/tasks/lists/{Id}/tasks |
Note
Any path starting with me
can also be used with users/{id}
instead of me
to target a specific user instead of the current user.
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
"id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource": "me/mailFolders('Inbox')/messages",
"applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
"changeType": "created",
"clientState": "secretClientValue",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"expirationDateTime": "2016-11-20T18:23:45.9356913Z",
"creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
"latestSupportedTlsVersion": "v1_2",
"notificationContentType": "application/json"
}
The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. If validation fails, the request to create the subscription returns a 400 Bad Request error.
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register now