Create subscription

Namespace: microsoft.graph

Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

See the table in the Permissions section for the list of resources that support subscribing to change notifications.

Some resources support the option to include encrypted resource data in change notifications. These resources include chatMessage, contact, event, message, and presence. For more information, see Set up change notifications that include resource data and Change notifications for Outlook resources in Microsoft Graph.

Permissions

Creating a subscription requires read scope to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permission.

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 the permissions, search for the following permissions in Permissions.

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

We recommend that you use the permissions as documented in the previous table. Due to security restrictions, Microsoft Graph subscriptions will not support write access permissions when only read access permissions are needed.

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. 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 and /users/{id}/chats/getAllMessages have licensing and payment requirements. /teams/getAllMessages and /chats/getAllMessages support both model=A and model=B query parameters, /me/chats/getAllMessages and /users/{id}/chats/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 and /chats/getAllMembers has licensing and payment requirements. /teams/getAllMembers and /chats/getAllMembers support both model=A and model=B query parameters. 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.

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.

OneDrive for Business and SharePoint support sending your application notifications of security events that occur on a driveItem. To subscribe to these events, add the prefer:includesecuritywebhooks header to your request to create a subscription. After the subscription is created, you will receive notifications when the permissions on an item change. This header is applicable to SharePoint and OneDrive for Business but not consumer OneDrive accounts.

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

Subscriptions on presence require any resource data included in a change notification to be encrypted. Always specify the encryptionCertificate parameter when creating a subscription to avoid failure. See more information about setting up change notifications to include resource data.

HTTP request

POST /subscriptions

Request headers

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

Request body

In the request body, supply a JSON representation of subscription object.

Response

If successful, this method returns 201 Created response code and a 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 to send a change notification when the user receives a new mail.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

In the request body, supply a JSON representation of the subscription object. The clientState and latestSupportedTlsVersion fields are optional.

Resources examples

The following are valid values for the resource property of the subscription:

Resource type Examples
Call records communications/callRecords
Chat message chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
Contacts me/contacts
Conversations groups('{id}')/conversations
Drives me/drive/root
Events me/events
Groups groups
List sites/{site-id}/lists/{list-id}
Mail me/mailfolders('inbox')/messages, me/messages
Presence /communications/presences/{id} (single user), /communications/presences?$filter=id in ('{id}','{id}',…) (multiple users)
printer print/printers/{id}/jobs
PrintTaskDefinition print/taskDefinitions/{id}/tasks
Security alert security/alerts?$filter=status eq 'New'
todoTask /me/todo/lists/{todoTaskListId}/tasks
Users users

Note: Any path starting with me can also be used with users/{id} instead of me to target a specific user instead of the current user.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

Notification endpoint validation

The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. If validation fails, the request to create the subscription returns a 400 Bad Request error.