Share via


Direct Batch Send

 

Updated: July 27, 2016

Sends a batch of notifications directly to a collection of device handles (a valid token as expressed by the Notification type). This API is available for Basic and Standard tier Notification Hub namespaces. Users of this API do not need to use Registrations or Installations. Instead, users of this API manage all devices on their own and use Azure Notification Hub solely as a pass through service to communicate with the various Push Notification Services.

At this time, Direct Batch Send supports up to 1000 devices per request.

Request

Method

Request URI

HTTP Version

POST

https://{namespace}.servicebus.windows.net/{NotificationHub}/messages/$batch?direct&api-version=2015-08

HTTP/1.1

Request Headers

The following table describes required and optional request headers.

Request Header

Description

Authorization

Token generated as specified in Shared Access Signature Authentication with Service Bus, or Service Bus authentication and authorization with Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS). For more information, see Common Concepts.

Content-Type

multipart/mixed; boundary="boundary-string"

The boundary string is used to separate each part according to the multipart content type defined in RFC1341. Each part starts with an encapsulation boundary, and then contains a body part consisting of header area, a blank line, and a body area.

ServiceBusNotification-Format

Set to a valid PlatformType value

  • windows

  • apple

  • gcm

  • windowsphone

  • adm

  • nokiax

  • baidu

x-ms-version

2015-04 (Supported by 2015-01 and later)

Request Body

The request body is multipart as defined in RFC1341. Each part starts with an encapsulation boundary, and then contains a body part consisting of header area, a blank line, and a body area. The blank link must not contain any whitespace. See the request examples below.

Based on the target platform type, the body format of a notification part will change to be compliant with each individual platform as covered in the native Send APIs below.

The devices part of the request body must be a JSON array of the device handles that will receive the notification.

Request Examples

The following is a WNS example.

POST https://{namespace}.servicebus.windows.net/{Notification Hub}/messages/$batch?direct&api-version=2015-08 HTTP/1.1
Content-Type: multipart/mixed; boundary = "simple-boundary"
Authorization: SharedAccessSignature sr=https%3a%2f%2f{Namespace}.servicebus.windows.net%2f{Notification Hub}%2fmessages%2f%24batch%3fdirect%26api-version%3d2015-08&sig={Signature}&skn=DefaultFullSharedAccessSignature
ServiceBusNotification-Format: windows
X-WNS-Type: wns/toast
Host: {Namespace}.servicebus.windows.net
Content-Length: 514
Expect: 100-continue
Connection: Keep-Alive


--simple-boundary
Content-type: text/xml
Content-Disposition: inline; name=notification

<toast><visual><binding template="ToastText01"><text id="1">Hello there!</text></binding></visual></toast>
--simple-boundary
Content-type: application/json
Content-Disposition: inline; name=devices

['https://db5.notify.windows.com/?token={Token1}','https://db5.notify.windows.com/?token={Token2}','https://db5.notify.windows.com/?token={Token3}']
--simple-boundary--

The following is a GCM example.

POST https://{Namespace}.servicebus.windows.net/{Notification Hub}/messages/$batch?direct&api-version=2015-08 HTTP/1.1
Content-Type: multipart/mixed; boundary="simple-boundary"
Authorization: SharedAccessSignature sr=https%3a%2f%2f{Namespace}.servicebus.windows.net%2f{Notification Hub}%2fmessages%2f%24batch%3fdirect%26api-version%3d2015-08&sig={Signature}&skn=DefaultFullSharedAccessSignature
ServiceBusNotification-Format: gcm
Host: {Namespace}.servicebus.windows.net
Content-Length: 431
Expect: 100-continue
Connection: Keep-Alive


--simple-boundary
Content-Type: application/json
Content-Disposition: inline; name=notification

{"data":{"message":"Hello via Direct Batch Send!!!"}}
--simple-boundary
Content-Type: application/json
Content-Disposition: inline; name=devices

['Device Token1','Device Token2','Device Token3']
--simple-boundary--

The following is an APNS example.

POST https://{Namespace}.servicebus.windows.net/{Notification Hub}/messages/$batch?direct&api-version=2015-08 HTTP/1.1
Content-Type: multipart/mixed; boundary="simple-boundary"
Authorization: SharedAccessSignature sr=https%3a%2f%2f{Namespace}.servicebus.windows.net%2f{Notification Hub}%2fmessages%2f%24batch%3fdirect%26api-version%3d2015-08&sig={Signature}&skn=DefaultFullSharedAccessSignature
ServiceBusNotification-Format: apple
Host: {Namespace}.servicebus.windows.net
Content-Length: 511
Expect: 100-continue
Connection: Keep-Alive


--simple-boundary
Content-Type: application/json
Content-Disposition: inline; name=notification

{"aps":{"alert":"Hello using APNS via Direct Batch Send!!!"}}
--simple-boundary
Content-Type: application/json
Content-Disposition: inline; name=devices

['Device Token1','Device Token2','Device Token3']
--simple-boundary--

Response

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

Response Codes

Code

Description

200

Created.

400

Could not find a part of the multipart content supplied.

401

Authorization failure. The access key was incorrect.

403

Quota exceeded or message too large; message was rejected.

404

No message branch at the URI.

413

Requested entity too large. The message size cannot be over 64Kb.

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

Response Headers

Response Header

Description

Content-Type

application/xml; charset=utf-8

Location

This header is only available for Standard tier Notification Hubs.

This header will contain the Notification Message ID. This is used with Per Message Telemetry: Get Notification Message Telemetry and correlating PNS Feedback. The location header uses the following format:

https://{your namespace}.servicebus.windows.net/{your hub name}/messages/{notification message id}?api-version=2015-04

Response Body

None

See Also

Direct Send
Send an APNS Native Notification
Send a GCM Native Notification
Send an MPNS Native Notification
Send a WNS Native Notification