Edit

Share via

Create and send a notification

  • Article

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.

Create and send a notification targeting a user through Microsoft Graph. The notification is stored in the Microsoft Graph notification feed store, and is sent to all app clients on all device endpoints that the user is signed in to.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ❌ ❌ ❌

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Notifications.ReadWrite.CreatedByApp Not available.
Delegated (personal Microsoft account) Notifications.ReadWrite.CreatedByApp Not available.
Application Not supported. Not supported.

HTTP request

POST /me/notifications/

Request headers

Name Description
Authorization The authorization header is used to pass the credentials of the calling party. Bearer {token}. Required.
X-UNS-ID The UserNotificationSubscriptionId that is returned by the Microsoft Graph notification service after creating a subscription and is used to target the specific user. Required.
Content-type application/json. Required.

Request body

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

Response

If successful, this method returns a 201 Created response code that indicates that the notification was successfully created and stored. The notification is then fanned-out to all specified endpoints with a valid subscription.

The following table lists the possible error and response codes that can be returned.

Error code Description
HttpStatusCode.BadRequest Body is an array (multiple notifications isn't supported).
HttpStatusCode.BadRequest Body doesn't match the contract for the API.
HttpStatusCode.Forbidden Caller is on the blocked list.
HttpStatusCode.MethodNotAllowed The HTTP method used isn't supported.
HttpStatusCode.BadRequest Unsupported headers are present in the request. Two headers aren't supported:

If-Modified-Since
If-Range
HttpStatusCode.UnsupportedMediaType The header Content-Encoding is present and has compression algorithm values other than Deflate or Gzip.
HttpStatusCode.BadRequest Invalid payload.
HttpStatusCode.Forbidden Caller isn't authorized to act on behalf of the user or send notification to the user.
HttpStatusCode.Unauthorized Request body contains invalid activity data types.
HttpStatusCode.OK Activity successfully created.
HttpStatusCode.NotAcceptable Request has been throttled or the server is busy.

Example

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/me/notifications/
Content-type: application/json

{
    "targetHostName": "graphnotifications.sample.windows.com",
    "appNotificationId": "testDirectToastNotification",
    "expirationDateTime": "2019-10-30T23:59:00.000Z",
    "payload": {
        "visualContent": {
            "title": "Hello World!",
            "body": "Notifications are Great!"
        }
    },
    "targetPolicy": {
        "platformTypes": [
	"windows",
	"ios",
	"android"
        ]
	},
    "priority": "High",
    "groupName": "TestGroup",
    "displayTimeToLive": "60"
}

Response

Here's an example of the corresponding response.

HTTP/1.1 201
client-request-id: 71e62feb-8d72-4912-8b2c-4cee9d89e781
content-length: 356
content-type: application/json
location: https://graph.microsoft.com/beta/me/activities/119081f2-f19d-4fa8-817c-7e01092c0f7d
request-id: 71e62feb-8d72-4912-8b2c-4cee9d89e781

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('graphnotify%40contoso.com')/notifications/$entity",
    "displayTimeToLive": 59,
    "expirationDateTime": "2019-10-28T22:05:36.25Z",
    "groupName": "TestGroup",
    "id": "119081f2-f19d-4fa8-817c-7e01092c0f7d",
    "priority": "High",
    "payload": {
        "visualContent": {
            "title": "Hello World!",
            "body": "Notifications are Great!"
        }
    }
}