Get notification message telemetry

  • Article

This API provides additional telemetry on the finished states of outgoing push notifications. It is designed to help monitor push notifications sent from a hub. The Notification ID that this API uses can be retrieved from the HTTP Location header included in the response of the REST API used to send the notification.

This Per Message Telemetry feature is also available for scheduled notifications.

This API is only available for Standard tier notification hubs.

Request

Method Request URI HTTP version
GET https://{namespace}.servicebus.windows.net/{NotificationHub}/messages/{notification message ID}?api-version=2016-07 HTTP/1.1

Request headers

The following table describes required and optional request headers.

Request header Description
Authorization SAS token generated as specified in Shared Access Signature Authentication with Service Bus.
x-ms-version 2016-07 (Supported by 2015-01 or later)

Request body

None.

Response

The response includes an HTTP status code and a set of response headers. Response body is returned on success.

Response codes

Code Description
200 The message telemetry was retrieved successfully. Telemetry data may be a partial response, depending on the number of devices targeted by the notification message that was sent, and how far the message has progress through our system for processing.
400 Message telemetry could not be retrieved because the request was malformed.
401 Authorization failure. The access key was incorrect.
403 Request rejected because this feature is not enabled for your SKU. Upgrade to Standard.
404 Telemetry does not exist. This error can occur when the notification ID is invalid.

For information about status codes, see Status and Error Codes.

Response headers

Response header Description
Content-type application/xml; charset=utf-8

Response body

The response body is a NotificationDetails document consisting of the following elements:

Element Description
NotificationId The ID passed to the request that identifies the notification message.
Location URI for the message
State Indicates message progress. State may be one of the following values:
  • Abandoned: Message processing has been abandoned. It happens when the message could not be processed within the acceptable time window. By default, it's 30 minutes.
  • Canceled: The user canceled this scheduled message.
  • Completed: Message processing has completed.
  • Enqueued: Message has been accepted but processing has not yet begun.
  • NoTargetFound: No devices were found to send this message.
  • Processing: Message processing has started.
  • Scheduled: Message is in queue and is sent at the scheduled time.
  • Unknown: Message processing is in an unknown state.
EnqueueTime Indicates the time the message was accepted.
StartTime Indicates when the notification hub service started work on the notification.
EndTime Indicates when the notification hub service finished work on the notification.
NotificationBody Body of the original notification message.
TargetPlatforms Indicates which platforms the notification targets. May contain the following values as a comma-delimited string:
  • windows
  • apple
  • gcm
  • windowsphone
  • adm
  • baidu
  • template
  • windowstemplate
  • appletemplate
  • gcmtemplate
  • windowsphonetemplate
  • admtemplate
  • baidutemplate
ApnsOutcomeCounts This element is present for notifications sent to Apple Push Notification Service. Contains a collection of Outcome instances.
MpnsOutcomeCounts This element is present for notifications sent to Microsoft Push Notification Service. Contains a collection of Outcome instances.
WnsOutcomeCounts This element is present for notifications sent to Windows Notification Service. Contains a collection of Outcome instances.
GcmOutcomeCounts This element is present for notifications sent to Google Cloud Messaging. Contains a collection of Outcome instances.
AdmOutcomeCounts This element is present for notifications sent to Amazon Device Messaging. Contains a collection of Outcome instances.
Outcome A collection of these instances make up the counts above for each platform notification service. Each outcome can be one of the named counts mentioned in the Outcomes section.
PnsErrorDetailsUri Requires Api-Version 2016-07 and above used for this API and the API sending the notification message.

PNS Error details are only fully available after the associated send operation is complete.

Gets the URI to a blob containing errors returned by each PNS involved. If no errors were reported by a PNS, this member isn't included in the response. You can use the Azure Storage API to read the blob. For more information, see, Get started with Azure Blob storage using .NET or Azure Storage Services REST API Reference Possible PNS errors include:
  • Invalid PNS Credentials
  • PNS Unreachable
  • BadChannel
  • ExpiredChannel
  • PnsThrottled
  • InvalidToken
  • WrongToken
  • Dropped
  • WrongChannel

Outcomes

Name Count description
AbandonedNotificationMessages Count of send requests to push service that were dropped because of a timeout.
BadChannel Communication to the push service failed because the channel was invalid.
ChannelDisconnected Push service disconnected.
ChannelThrottled Push service denied access due to throttling.
Dropped Push service indicates that the message was dropped.
ExpiredChannel Communication to the push service failed because the channel expired.
InvalidCredentials Credentials used to authenticate to the push service failed.
InvalidNotificationSize Push request is too large.
NoTargets Count of requests that found nothing to send to.
PnsInterfaceError Push service contract communication failed.
PnsServerError Push service indicated that an error happened on their side.
PnsUnavailable Push service is not available.
PnsUnreachable Push service was unresponsive.
Skipped Count of duplicate registrations (same PNS handle found, different registration ID).
Success Successfully sent the request to some number of devices.
Throttled Push service denied access due to throttling.
UnknownError An unknown error happened.
WrongToken The PNS handle was not recognized by the PNS as a valid handle.

Here is an example telemetry from sending a notification to WNS:

<NotificationDetails xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <NotificationId>{Your message id}</NotificationId>
  <Location>sb://{Your namespace}.servicebus.windows.net/{your hub name}/messages/{your message id}?api-version=2015-04</Location>
  <State>Completed</State>
  <EnqueueTime>2015-11-02T21:19:43Z</EnqueueTime>
  <StartTime>2015-11-02T21:19:43.9926996Z</StartTime>
  <EndTime>2015-11-02T21:19:43.9926996Z</EndTime>
  <NotificationBody>&lt;?xml version="1.0" encoding="utf-16"?&gt;&lt;toast&gt;&lt;visual&gt;&lt;binding template="ToastText01"&gt;&lt;text id="1"&gt;Hello from a .NET App!&lt;/text&gt;&lt;/binding&gt;&lt;/visual&gt;&lt;/toast&gt;</NotificationBody>
  <TargetPlatforms>windows</TargetPlatforms>
  <WnsOutcomeCounts>
    <Outcome>
      <Name>Success</Name>
      <Count>3</Count>
    </Outcome>
    <Outcome>
      <Name>WrongToken</Name>
      <Count>1</Count>
    </Outcome>
  </WnsOutcomeCounts>
  <PnsErrorDetailsUri>{Blob uri}</PnsErrorDetailsUri>
</NotificationDetails>

See Also

Send a template notification
Send an APNS native notification
Send a GCM native notification
Send an MPNS native notification
Send a WNS native notification