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,55 @@ 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 a push notification payload to multiple devices or browsers in a single request by specifying a list of recipients and corresponding payloads.
+
+h6. POST rest.ably.io/push/admin/batch/publish
+
+The request body is an array of objects of the form:
+
+bc[json]. {
+  recipient: <object>
+  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

@@ -1226,3 +1226,54 @@ final message = Message(name: 'name', data: 'data', extras: extras);
 channel = rest.channels.get('pushenabled:foo');
 channel.publish(message);
 ```
+
+
+h2(#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 for when you need to send a large number of push notifications on an ad-hoc basis (ie when using push channel subscriptions is not practical).
+
+The batch push endpoint accepts a JSON array of @PushPublishSpec@ objects, each of which contains a @recipient@ and a @payload@, where @payload@ is the same as the payload you would use in a normal direct publish request.
+
+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/admin/batch/publish', null, [
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 1', body: 'Example push notification from Ably.' }
+    }
+  },
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 2', body: 'Example push notification from Ably.' }
+    }
+  }
+])
+```
+
+```[rest_nodejs]
+await rest.request('POST', '/push/admin/batch/publish', null, [
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 1', body: 'Example push notification from Ably.' }
+    }
+  },
+  {
+    recipient: {
+      deviceId: 'xxxxxxxxxxx'
+    },
+    payload: {
+      notification: { title: 'Message 2', body: 'Example push notification from Ably.' }
+    }
+  }
+])
+```