add batch push publish docs

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 notifications per request (note that each recipient for a given payload counts as a separate notification).
+
+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

content/push/publish.textile

@@ -141,6 +141,8 @@ h2(#direct-publishing). Publish directly
 
 Direct publishing sends push notifications directly to individual devices via the  "Ably SDK":https://ably.com/docs/sdks, bypassing the intermediary of channels. This approach delivers personalized or precise notifications customized for individual users. Direct publishing proves beneficial during the transition phase to Ably's platform and when the objective is to engage existing push notification devices.
 
+Direct publishing is also available in "batch mode":#via-batch-push-api, enabling you to publish to a large number of devices in one request.
+
 Push notifications are targeted explicitly towards devices identified by:
 
 * "@deviceId@":#device-id
@@ -778,6 +780,70 @@ var notification = new
 rest.Push.Admin.Publish(recipient, notification);
 ```
 
+h3(#via-batch-push-api). Publish via batch push API
+
+The batch push API enables 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 contain 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 notifications per request (each recipient for a given payload counts as a separate notification).
+
+The following example shows how to publish multiple push notifications in one request using the batch API with the generic REST "@request()@":/docs/api/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.