Update subscription

Namespace: microsoft.graph

Renew a subscription by extending its expiry time.

The table in the Permissions section lists the resources that support subscribing to change notifications.

Subscriptions expire after a length of time that varies by resource type. In order to avoid missing change notifications, an app should renew its subscriptions well in advance of their expiry date. See subscription for maximum length of a subscription for each resource type.

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.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
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
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
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}) 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.

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.

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.

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

Additional limitations apply for subscriptions on OneDrive items. The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

On 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.

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.

presence

presence subscriptions require encryption for notifications that include resource data. Subscription creation fails if encryptionCertificate and encryptionCertificateId aren't specified when notifications need to include resource data. For details about presence subscriptions, see Get change notifications for presence updates in Microsoft Teams.

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

PATCH /subscriptions/{id}

Request headers

Name Type Description
Authorization string Bearer {token}. Required. Learn more about authentication and authorization.

Request body

In the request body, supply only the values for properties to update. Existing properties that aren't included in the request body maintain their previous values or are recalculated based on changes to other property values.

The following table specifies the properties that can be updated.

The request body must include at least one of the properties listed.

Name Type Description
expirationDateTime DateTimeOffset Specifies the date and time in UTC when the subscription expires. For the maximum supported subscription length of time varies depending on the resource.
notificationUrl String This URL must make use of the HTTPS protocol. Any query string parameter included in the notificationUrl property is included in the HTTP POST request when Microsoft Graph sends the change notifications.

Response

If successful, this method returns a 200 OK response code and subscription object in the response body.

For details about how errors are returned, see Error responses.

Example

Request

The following example shows a request.

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-type: application/json

{
   "expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}

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": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType":"created,updated",
  "clientState":"subscription-identifier",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-22T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false,
  "notificationContentType": "application/json"
}