Get subscription
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.
Retrieve the properties and relationships of a subscription.
See the table in the Permissions section for the list of resources that support subscribing to change notifications.
This API is available in the following national cloud deployments.
| Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
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 more privileged permissions, search for the following permissions in Permissions.
Note
Some resources support change notifications in multiple scenarios, each of which may require different permissions. In those cases, use the resource path to differentiate the scenarios.
| Supported resource | Delegated (work or school account) | Delegated (personal Microsoft account) | Application |
|---|---|---|---|
| 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 recording 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 |
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 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 |
| online meeting | Not supported. | Not supported. | OnlineMeetings.Read.All, OnlineMeetings.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 |
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 |
| 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:
- OnlineMeetingRecording.Read.Chat
- OnlineMeetingTranscript.Read.Chat
- ChatSettings.Read.Chat
- ChatSettings.ReadWrite.Chat
- Chat.Manage.Chat
- ChannelMessage.Read.Group
- ChatMember.Read.Chat
chatMessage
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.
You must 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
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
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.
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.
Request example
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"
}
driveItem
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 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.
contact, event, and message
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:
- Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
- Don't use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.
onlineMeetings, presence
onlineMeetings and presence subscriptions require encryption for notifications with resource data. Subscription creation fails if encryptionCertificate and encryptionCertificateId aren't specified if resource data is desired in notifications. For details about online meeting subscriptions, see Get change notifications for online meetings.
virtualEventWebinar
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.
HTTP request
GET /subscriptions/{id}
Optional query parameters
This method supports the OData Query Parameters to help customize the response.
Request headers
| Name | Type | Description |
|---|---|---|
| Authorization | string | Bearer {token}. Required. |
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK response code and subscription object in the response body.
Examples
Request
The following example shows a request.
GET https://graph.microsoft.com/beta/subscriptions/{id}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-type: application/json
{
"id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource":"me/messages",
"applicationId" : "string",
"changeType":"created,updated",
"clientState":"secretClientValue",
"notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
"lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"creatorId": "string",
"latestSupportedTlsVersion": "v1_2",
"encryptionCertificate": "",
"encryptionCertificateId": "",
"includeResourceData": false,
"notificationContentType": "application/json"
}
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for