| title | description | ms.localizationpriority | author | ms.subservice | doc_type |
|---|---|---|---|---|---|
Create subscription |
Subscribes a listener application to receive change notifications when data on the Microsoft Graph changes. |
high |
keylimesoda |
change-notifications |
apiPageType |
Namespace: microsoft.graph
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.
[!INCLUDE national-cloud-support]
Creating a subscription requires read scope to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permission.
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.
| Supported resource | Delegated (work or school account) | Delegated (personal Microsoft account) | Application |
|---|---|---|---|
| callRecord (/communications/callRecords) | Not supported | Not supported | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings All recordings in an organization. |
Not supported. | Not supported. | OnlineMeetingRecording.Read.All |
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings All recordings 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 |
callTranscript communications/onlineMeetings/getAllTranscripts All transcripts in an organization. |
Not supported. | Not supported. | OnlineMeetingTranscript.Read.All |
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts All transcripts 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 |
| channel (/teams/getAllChannels – all channels in an organization) | Not supported | Not supported | Channel.ReadBasic.All, ChannelSettings.Read.All |
| channel (/teams/{id}/channels) | 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}) | 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 |
| chatMessage (/teams/{id}/channels/{id}/messages) | ChannelMessage.Read.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) | Chat.Read, Chat.ReadWrite | Not supported | Chat.Read.All |
| chatMessage (/chats/getAllMessages -- all chat messages in 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) | Not supported | Not supported | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| conversationMember (/chats/{id}/members) | 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/{id}/members) | TeamMember.Read.All | Not supported | TeamMember.Read.All |
| conversationMember (/teams/{id}/channels/getAllMembers) | Not supported | Not supported | ChannelMember.Read.All |
| driveItem (user's personal OneDrive) | Not supported | Files.ReadWrite | Not supported |
| driveItem (OneDrive for Business) | 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 |
| 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 |
| team (/teams – all teams in an organization) | Not supported | Not supported | Team.ReadBasic.All, TeamSettings.Read.All |
| team (/teams/{id}) | Team.ReadBasic.All, TeamSettings.Read.All | Not supported | Team.ReadBasic.All, TeamSettings.Read.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 |
We recommend that you use the permissions as documented in the previous table. Due to security restrictions, Microsoft Graph subscriptions don't support write access permissions when only read access permissions are needed.
Note: Permissions marked with * use resource-specific consent.
[!INCLUDE teams-subscription-notes]
Additional limitations apply for 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 Business, you can subscribe to only the root folder. Change notifications are sent for the requested types of 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 Business 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 is applicable to SharePoint and OneDrive for Business but not consumer OneDrive accounts.
You can subscribe to changes in Outlook contact, event, or message resources.
[!INCLUDE outlook-subscription-notes]
Subscriptions on presence require any resource data included in a change notification to be encrypted. Always specify the encryptionCertificate parameter when creating a subscription to avoid failure. See more information about setting up change notifications to include resource data.
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. |
In the request body, supply a JSON representation of subscription object.
If successful, this method returns 201 Created response code and a subscription object in the response body.
For details about how errors are returned, see Error responses.
The following example shows a request to send a change notification when the user receives a new mail.
POST https://graph.microsoft.com/v1.0/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"
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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 of the subscription:
| Resource type | Examples |
|---|---|
| Call records | communications/callRecords |
| callRecording | communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings |
| callTranscript | communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts |
| Chat message | chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages |
| Contacts | me/contacts |
| Conversations | groups('{id}')/conversations |
| Drives | me/drive/root |
| Events | me/events |
| Groups | groups |
| List | sites/{site-id}/lists/{list-id} |
me/mailfolders('inbox')/messages, me/messages |
|
| 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 |
| Security alert | security/alerts?$filter=status eq 'New' |
| todoTask | /me/todo/lists/{todoTaskListId}/tasks |
| Users | users |
Note: Any path starting with
mecan also be used withusers/{id}instead ofmeto 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/v1.0/$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.