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.

Caution

Existing apps that use this feature with baseTask or baseTaskList should be updated, as the to-do API set built on these resources is deprecated as of May 31, 2022. That API set will stop returning data on August 31, 2022. Please use the API set built on todoTask.

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.

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.

Permissions marked with * use resource-specific consent.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
baseTask (deprecated) Tasks.ReadWrite Tasks.ReadWrite Not supported
callRecord Not supported Not supported CallRecords.Read.All
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
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

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. Before you can create a chatMessage subscription with application permissions, you might need to request access. For details, see Protected APIs in Microsoft Teams.

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 have licensing and payment requirements. /teams/getAllMessages and /chats/getAllMessages support both model=A and model=B query parameters, /me/chats/getAllMessages, /users/{id}/chats/getAllMessages, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages support only model=B. If no model is specified, evaluation mode will be used.

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 have licensing and payment requirements. /teams/getAllMembers and /chats/getAllMembers support both model=A and model=B query parameters. /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers supports only model=B. If no model is specified, evaluation mode will be used.

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.

Request example

Specify the model query parameter in the resource property in the request body.

POST https://graph.microsoft.com/beta/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

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 cannot subscribe to drive or driveItem instances that are not 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 cannot 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.
    • Do not 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 will fail if encryptionCertificate and encryptionCertificateId are not specified if resource data is desired in notifications. For details about online meeting subscriptions, see Get change notifications for online meetings.

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

Do not 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.

Example

Request

Here is an example of the request.

GET https://graph.microsoft.com/beta/subscriptions/{id}
Response

Here is an example of 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"
}