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

Renew a subscription by extending its expiry time.

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.

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 how to choose permissions, see Permissions.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
callRecord Not supported Not supported CallRecords.Read.All
chatMessage (/teams/{id}/channels/{id}/messages) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All Not supported ChannelMessage.Read.All
chatMessage (/teams/allMessages -- 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/allMessages -- all chat messages in organization) Not supported Not supported Chat.Read.All
contact Contacts.Read Contacts.Read Contacts.Read
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.ReadBasic, Mail.Read
presence Presence.Read.All Not supported Not supported
security alert SecurityEvents.ReadWrite.All Not supported SecurityEvents.ReadWrite.All
user User.Read.All User.Read.All User.Read.All

chatMessage

chatMessage subscriptions with delegated permissions do not support resource data (includeResourceData must be false), and do not require encryption.

chatMessage subscriptions with application permissions include resource data, and require encryption. Subscription creation will fail if encryptionCertificate is not specified. Before creating a chatMessage subscription, you must request access. For details, see Protected APIs in Microsoft Teams.

Note: /teams/allMessages and /chats/allMessages are currently in preview. During the preview, you may use this API without fees, subject to the Microsoft APIs Terms of Use. However, users of apps that use the API might be required to have subscriptions to specific Microsoft 365 offerings. Upon general availability, Microsoft may require you or your customers to pay additional fees based on the amount of data accessed through the API.

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 cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

contact, event, and message

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

  • Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. That means, 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.

presence

presence subscriptions require encryption. Subscription creation will fail if encryptionCertificate is not specified.

HTTP request

PATCH /subscriptions/{id}

Request headers

Name Type Description
Authorization string Bearer {token}. Required.

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

Here is an example of the request.

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

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

Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 252

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType":"created,updated",
  "clientState":"secretClientValue",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime":"2016-11-22T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2"
}