add batch push publish docs

Author: owenpearson

Diff for: content/api/rest-api.textile

@@ -29,6 +29,7 @@ jump_to:
     - list channel subscriptions#list-channel-subscriptions
     - list channels#list-channels
     - publish directly to device#push-publish
+    - publish via batch push API#push-publish-batch
   Authentication API:
     - requestToken#request-token
     - revokeTokens#revoke-tokens
@@ -1152,6 +1153,56 @@ A successful request returns an empty response.
 
 An unsuccessful request returns an error.
 
+h3(#push-publish-batch). Publish via batch push API
+
+Convenience endpoint to deliver multiple push notification payloads to multiple devices or browsers in a single request by specifying a list of recipients and corresponding payloads.
+Currently the batch push endpoint allows a maximum of 10,000 recipients per request (recipients are counted per payload, so publishing two payloads to the same recipient counts as two recipients).
+
+h6. POST rest.ably.io/push/batch/publish
+
+The request body is an array of objects of the form:
+
+bc[json]. {
+  recipient: <recipient object or array of recipient objects>
+  payload: <object>
+}
+
+Where the recipient and payload fields are the same as those used in the "Publish a push notification to a single device":#push-publish endpoint.
+
+Example request:
+
+bc[sh]. curl -X POST https://rest.ably.io/push/admin/batch/publish \
+ -u "{{API_KEY}}" \
+ -H "Content-Type: application/json" \
+ --data \
+ '
+[
+  {
+    "recipient": {
+      "deviceId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+    },
+    "payload": {
+      "notification": {
+        "title": "Message 1",
+        "body": "Example push notification from Ably."
+      }
+    }
+  },
+  {
+    "recipient": {
+      "clientId": "myClientId"
+    },
+    "payload": {
+      "notification": {
+        "title": "Message 2",
+        "body": "Example push notification from Ably."
+      }
+    }
+  }
+]
+'
+
+
 h2(#authentication). Authentication
 
 h3(#request-token). Request an access token

Diff for: content/push/publish.textile

@@ -778,6 +778,66 @@ var notification = new
 rest.Push.Admin.Publish(recipient, notification);
 ```
 
+h3(#via-batch-push-api). Publish via batch push API
+
+The batch push API allows you to publish push notifications to multiple devices or browsers in a single request. This is useful when you need to send a large number of distinct push notifications to multiple recipients. If you are publishing the same notification to multiple recipients, prefer publishing "via channels":#via-channels.
+The batch push endpoint accepts a JSON array of @PushPublishSpec@ objects, each of which contains a @recipient@ or array of recipients, and a @payload@, where @payload@ is the same as the payload you would use in a normal direct publish request.
+Currently the batch push endpoint allows a maximum of 10,000 recipients per request (recipients are counted per payload, so publishing two payloads to the same recipient counts as two recipients).
+
+The following example shows how to publish multiple push notifications in one request using the batch API with the generic REST SDK @request@ method:
+
+```[rest_javascript]
+await rest.request('POST', '/push/batch/publish', null, [
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 1', body: 'Example push notification from Ably.' }
+    }
+  },
+  {
+    recipient: [
+      {
+        deviceId: 'xxxxxxxxxxx'
+      },
+      {
+        deviceId: 'xxxxxxxxxxx',
+      }
+    ],
+    payload: {
+      notification: { title: 'Message 2', body: 'Example push notification from Ably.' }
+    }
+  }
+])
+```
+
+```[rest_nodejs]
+await rest.request('POST', '/push/batch/publish', null, [
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 1', body: 'Example push notification from Ably.' }
+    }
+  },
+  {
+    recipient: [
+      {
+        deviceId: 'xxxxxxxxxxx'
+      },
+      {
+        deviceId: 'xxxxxxxxxxx',
+      }
+    ],
+    payload: {
+      notification: { title: 'Message 2', body: 'Example push notification from Ably.' }
+    }
+  }
+])
+```
+
 h2(#via-channels). Publish via channels
 
 Publishing via channels is modeled on Ably's "channel":#channels infrastructure, facilitating the delivery of push notifications across a network of subscribed devices or browsers. This process publishes messages through predefined channels, which devices or browsers must "subscribe":#sub-channels to in order to   receive updates. This process ensures registered devices or browsers in the specified channels receive the correct push notifications. Publishing via channels is particularly useful for publishing notifications to multiple groups with varying privileges.