| title | Get subscription |
|---|---|
| description | Retrieve the properties and relationships of a subscription. |
| ms.localizationpriority | high |
| author | jessieli-ad |
| ms.subservice | change-notifications |
| doc_type | apiPageType |
| ms.date | 08/01/2024 |
Namespace: microsoft.graph
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.
[!INCLUDE national-cloud-support]
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.
| 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 |
| callRecord | 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 |
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) | 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) | Not supported | 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 |
| 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 |
| 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 |
| 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}) | 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 |
Note: Permissions marked with * use resource-specific consent.
[!INCLUDE teams-subscription-notes]
[!INCLUDE copilot-aiinteraction-subscription-notes.md]
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.
You can subscribe to changes in Outlook contact, event, or message resources.
[!INCLUDE outlook-subscription-notes]
Subscriptions on presence chatMessage subscriptions can be specified to include resource data (includeResourceData set to true). In that case, encryption is required and the subscription creation fails if an encryptionCertificate and encryptionCertificateId aren't specified. For details about presence subscriptions, see Get change notifications for presence updates in Microsoft Teams.
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.
GET /subscriptions/{id}This method supports the OData Query Parameters to help customize the response.
| Name | Type | Description |
|---|---|---|
| Authorization | string | Bearer {token}. Required. Learn more about authentication and authorization. |
Don't supply a request body for this method.
If successful, this method returns a 200 OK response code and subscription object in the response body.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/subscriptions/{id}
[!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]
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"
}