Push notification service request and response headers (Windows Runtime apps)

This topic describes the service-to-service web APIs and protocols required to send a push notification.

See the Windows Push Notification Services (WNS) overview for a conceptual discussion of push notification and WNS concepts, requirements, and operation.

Requesting and receiving an access token

This section describes the request and response parameters involved when you authenticate with the WNS.

Access token request

An HTTP request is sent to WNS to authenticate the cloud service and retrieve an access token in return. The request is issued to https://login.live.com/accesstoken.srf using Secure Sockets Layer (SSL).

Access token request parameters

The cloud service submits these required parameters in the HTTP request body, using the "application/x-www-form-urlencoded" format. You must ensure that all parameters are URL encoded.

Access token response

WNS authenticates the cloud service and, if successful, responds with a "200 OK", including the access token. Otherwise, WNS responds with an appropriate HTTP error code as described in the OAuth 2.0 protocol draft.

Access token response parameters

An access token is returned in the HTTP response if the cloud service successfully authenticated. This access token can be used in notification requests until it expires. The HTTP response uses the "application/json" media type.

Response code

Example

The following shows an example of a successful authentication response:

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer",
     "expires_in": 86400
 }

Sending a notification request and receiving a response

This section describes the headers involved in an HTTP request to WNS to deliver a notification and those involved in the reply.

• Send notification request
• Send notification response
• Unsupported HTTP features

Send notification request

When sending a notification request, the calling app makes an HTTP request over SSL, addressed to the channel Uniform Resource Identifier (URI). "Content-Length" is a standard HTTP header that must be specified in the request. All other standard headers are either optional or not supported.

In addition, the custom request headers listed here can be used in the notification request. Some headers are required while others are optional.

Request parameters

Important notes

• Content-Length and Content-Type are the only standard HTTP headers that are included in the notification delivered to the client, regardless of whether other standard headers were included in the request.
• All other standard HTTP headers are either ignored or return an error if the functionality is not supported.
• Starting in February 2023, WNS will cache only one tile notification when the device is offline.

Authorization

The authorization header is used to specify the credentials of the calling party, following the OAuth 2.0 authorization method for bearer tokens.

The syntax consists of a string literal "Bearer", followed by a space, followed by your access token. This access token is retrieved by issuing the access token request described above. The same access token can be used on subsequent notification requests until it expires.

This header is required.

Authorization: Bearer <access-token>

X-WNS-Type

These are the notification types supported by WNS. This header indicates the type of notification and how WNS should handle it. After the notification reaches the client, the actual payload is validated against this specified type. This header is required.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

X-WNS-Cache-Policy

When the notification target device is offline, WNS will cache one badge, one tile, and one toast notification for each channel URI. By default, raw notifications are not cached, but if raw notification caching is enabled, one raw notification is cached. Items are not held in the cache indefinitely and will be dropped after a reasonable period of time. Otherwise, the cached content is delivered when the device next comes online.

X-WNS-Cache-Policy: cache | no-cache

X-WNS-RequestForStatus

Specifies whether the response should include the device status and WNS connection status. This header is optional.

    X-WNS-RequestForStatus: true | false

X-WNS-Tag

Assigns a tag label to a notification. The tag is used in the replacement policy of the tile in the notification queue when the app has opted for notification cycling. If a notification with this tag already exists in the queue, a new notification with the same tag takes its place.

    X-WNS-Tag: <string value>

X-WNS-TTL

Specifies the TTL (expiration time) for a notification. This is not typically needed, but can be used if you want to ensure that your notifications are not displayed later than a certain time. The TTL is specified in seconds and is relative to the time that WNS receives the request. When a TTL is specified, the device will not display the notification after that time. Note that this could result in the notification never being shown at all if the TTL is too short. In general, an expiration time will be measured in at least minutes.

This header is optional. If no value is specified, the notification does not expire and will be replaced under the normal notification replacement scheme.

X-WNS-TTL: <integer value>

X-WNS-SuppressPopup

X-WNS-SuppressPopup: true | false

X-WNS-Group

X-WNS-Group: <string value>

X-WNS-Match

X-WNS-Match: type:wns/toast;group=<string value>;tag=<string value> | type:wns/toast;group=<string value> | type:wns/toast;tag=<string value> | type:wns/toast;all

Send notification response

After WNS processes the notification request, it sends an HTTP message in response. This section discusses the parameters and headers that can be found in that response.

Response parameters

X-WNS-Debug-Trace

This header returns useful debugging information as a string. We recommend that this header be logged to help developers debug issues. This header, together with the X-WNS-Msg-ID header and MS-CV, are required when reporting an issue to WNS.

X-WNS-Debug-Trace: <string value>

X-WNS-DeviceConnectionStatus

This header returns the device status to the calling application, if requested in the X-WNS-RequestForStatus header of the notification request.

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

X-WNS-Error-Description

This header provides a human-readable error string that should be logged to help with debugging.

X-WNS-Error-Description: <string value>

X-WNS-Msg-ID

This header is used to provide the caller with an identifier for the notification. We recommended that this header be logged to help debug issues. This header, together with the X-WNS-Debug-Trace and MS-CV, are required when reporting an issue to WNS.

X-WNS-Msg-ID: <string value>

X-WNS-Status

This header describes how WNS handled the notification request. This can be used rather than interpreting response codes as success or failure.

X-WNS-Status: received | dropped | channelthrottled

MS-CV

This header provides a Correlation Vector related to the request which is primarily used for debugging. If a CV is provided as part of the request then WNS will use this value, else WNS will generate and respond back with a CV. This header, together with the X-WNS-Debug-Trace and X-WNS-Msg-ID header, are required when reporting an issue to WNS.

MS-CV: <string value>

Response codes

Each HTTP message contains one of these response codes. WNS recommends that developers log the response code for use in debugging. When developers report an issue to WNS, they are required to provide response codes and header information.

Unsupported HTTP features

The WNS Web Interface supports HTTP 1.1 but does not support the following features:

• Chunking
• Pipelining (POST is not idempotent)
• Although supported, developers should disable Expect-100 as that introduces latency when sending a notification.