From e6ca96a1b036d22a79d40bfab3bb4f2a19f8519f Mon Sep 17 00:00:00 2001 From: Marat Alekperov Date: Wed, 22 Apr 2026 16:12:11 +0200 Subject: [PATCH] docs(cli): improve push publish and batch-publish documentation - Clarify --message flag: accepts plain text, JSON data, or full message object - Add example showing full message object format for push publish - Update batch-publish payload description with @filename syntax and message field - Add batch-publish example showing "message" field in channel items Co-Authored-By: Claude Sonnet 4.6 --- src/pages/docs/cli/push/batch-publish.mdx | 48 +++++++++++++----- src/pages/docs/cli/push/publish.mdx | 60 +++++++++++++++-------- 2 files changed, 77 insertions(+), 31 deletions(-) diff --git a/src/pages/docs/cli/push/batch-publish.mdx b/src/pages/docs/cli/push/batch-publish.mdx index c34cec0407..bb1ae503a4 100644 --- a/src/pages/docs/cli/push/batch-publish.mdx +++ b/src/pages/docs/cli/push/batch-publish.mdx @@ -18,7 +18,9 @@ ably push batch-publish [payload] [options] ### `payload` -A JSON array of push notification payloads. This can be provided as an inline JSON string, a file path, or `-` to read from stdin. +A JSON array of push notification payloads. This can be provided as an inline JSON string, a file path (for example `./notifications.json` or `@notifications.json`), or `-` to read from stdin. + +Each item must have either a `recipient` or `channels` key. Items with `channels` are routed via channel-based push. Channel items may include an optional `message` field with realtime message data (plain text or JSON object) to publish alongside the push notification. In a JSON object, the recognized message fields `name`, `data`, and `extras` are mapped directly; any other fields are merged into `data`. ## Options @@ -40,7 +42,7 @@ Enable verbose logging. Can be combined with `--json` or `--pretty-json`. ## Examples -Publish with an inline JSON payload: +Publish to multiple recipients with an inline JSON payload: ```shell @@ -56,6 +58,8 @@ ably push batch-publish @notifications.json ``` +See notification file example [below](#notifications-json-file). + Publish from stdin: @@ -64,7 +68,7 @@ cat notifications.json | ably push batch-publish - ``` -Batch publish a push notification to a specific client: +Publish to a specific client: ```shell @@ -72,7 +76,7 @@ ably push batch-publish '[{"recipient":{"clientId":"user-456"},"payload":{"notif ``` -Batch publish a data-only push notification to a device: +Publish a data-only notification to a device: ```shell @@ -80,31 +84,31 @@ ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"dat ``` -Batch publish to a channel with force option: +Publish to a channel with a message string and a force option: ```shell -ably push batch-publish '[{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}}}]' --force +ably push batch-publish '[{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}},"message":"Hello from push"}]' --force ``` -Batch publish to multiple channels: +Publish to multiple channels with a message JSON object: ```shell -ably push batch-publish '[{"channels":["channel-1","channel-2"],"payload":{"notification":{"title":"Alert","body":"Message"}}}]' --force +ably push batch-publish '[{"channels":["channel-1","channel-2"],"payload":{"notification":{"title":"Alert","body":"Message"}},"message":{"name":"alert","data":"New alert"}}]' --force ``` -Batch publish combining device and channel recipients: +Publish to device and channel recipients in one batch: ```shell -ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"notification":{"title":"Hello","body":"World"}}},{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}}}]' --force +ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"notification":{"title":"Hello","body":"World"}}},{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}},"message":{"name":"greeting","data":"Hello from push"}}]' --force ``` -Batch publish from a file and output the result in JSON format: +Publish from a file and output in JSON format: ```shell @@ -112,6 +116,28 @@ ably push batch-publish ./notifications.json --json --force ``` +### Notifications.json file + + +```json +[ + { + "recipient": {"deviceId": "device-123"}, + "payload": { + "notification": {"title": "Hello", "body": "World"} + } + }, + { + "channels": ["my-channel"], + "payload": { + "notification": {"title": "Hello", "body": "World"} + }, + "message": {"name": "greeting", "data": "Hello from push"} + } +] +``` + + ## See also * [Push](/docs/cli/push) — Explore all `ably push` commands. diff --git a/src/pages/docs/cli/push/publish.mdx b/src/pages/docs/cli/push/publish.mdx index a6e507ef62..4892994826 100644 --- a/src/pages/docs/cli/push/publish.mdx +++ b/src/pages/docs/cli/push/publish.mdx @@ -34,7 +34,7 @@ The target channel name. Publishes a push notification via the channel using `ex ### `--message` -Realtime message data to include alongside the push notification. Accepts either plain text or raw JSON, and the value is used as the realtime message `data` payload rather than a full message object. Only applies when publishing via `--channel`. +Realtime message to include alongside the push notification. Accepts plain text, or a JSON object. In a JSON object, the recognized message fields `name`, `data`, and `extras` are mapped directly; any other fields are merged into `data`. Only applies when publishing via `--channel`. ### `--title` @@ -102,7 +102,7 @@ Enable verbose logging. Can be combined with `--json` or `--pretty-json`. ## Examples -Publish a push notification to a device: +Publish to a device: ```shell @@ -110,7 +110,7 @@ ably push publish --device-id "device123" --title "Hello" --body "World" ``` -Publish a push notification to a client: +Publish to a client: ```shell @@ -118,15 +118,15 @@ ably push publish --client-id "user456" --title "Update" --body "New content ava ``` -Publish a push notification to a channel: +Publish to a channel: ```shell -ably push publish --channel "announcements" --title "News" --body "Breaking update" --force +ably push publish --channel "announcements" --title "News" --body "Breaking update" --message "Breaking update" --force ``` -Publish with a custom payload: +Publish to a device with a custom payload: ```shell @@ -134,7 +134,7 @@ ably push publish --device-id "device123" --payload '{"notification":{"title":"C ``` -Publish a push notification to a device with additional data: +Publish to a device with additional data: ```shell @@ -142,7 +142,7 @@ ably push publish --device-id device-123 --title Hello --body World --data '{"ke ``` -Publish to a device using a custom JSON payload: +Publish to a device using a JSON payload string: ```shell @@ -158,7 +158,9 @@ ably push publish --device-id device-123 --payload ./notification.json ``` -Publish to a client using a custom JSON payload: +See notification file example [below](#notification-json-file). + +Publish to a client using a JSON payload string: ```shell @@ -166,31 +168,31 @@ ably push publish --client-id client-1 --payload '{"notification":{"title":"Hell ``` -Publish to a channel with additional data: +Publish to a channel with a message string and additional data: ```shell -ably push publish --channel my-channel --title Hello --body World --data '{"key":"value"}' +ably push publish --channel my-channel --title Hello --body World --data '{"key":"value"}' --message 'Hello from push' ``` -Publish to a channel using a custom JSON payload: +Publish to a channel using a JSON payload string: ```shell -ably push publish --channel my-channel --payload '{"notification":{"title":"Hello","body":"World"},"data":{"key":"value"}}' +ably push publish --channel my-channel --payload '{"notification":{"title":"Hello","body":"World"},"data":{"key":"value"}}' --message 'Hello from push' ``` -Publish a push notification to a channel with a realtime message string: +Publish to a channel with a message JSON object (a full message object with `name` and `data` fields): ```shell -ably push publish --channel my-channel --title Hello --body World --message 'Hello from push' +ably push publish --channel my-channel --title Hello --body World --message '{"name":"greeting","data":"Welcome back"}' ``` -Publish a push notification to a channel with a realtime message JSON payload: +Publish to a channel with a message `data` JSON payload (a JSON object containing arbitrary message `data` fields): ```shell @@ -198,15 +200,17 @@ ably push publish --channel my-channel --title Hello --body World --message '{"e ``` -Publish to a channel using a payload from a file: +Publish to a channel using a payload from a file and a string message: ```shell -ably push publish --channel my-channel --payload ./notification.json +ably push publish --channel my-channel --payload ./notification.json --message 'Hello from push' ``` -Publish to a device using raw recipient attributes: +See notification file example [below](#notification-json-file). + +Publish using raw recipient attributes: ```shell @@ -214,7 +218,7 @@ ably push publish --recipient '{"transportType":"apns","deviceToken":"token123"} ``` -Publish a push notification and output the result in JSON format: +Publish and output in JSON format: ```shell @@ -222,6 +226,22 @@ ably push publish --device-id device-123 --title Hello --body World --json ``` +### Notification.json file + + +```json +{ + "notification": { + "title": "Hello", + "body": "World" + }, + "data": { + "key": "value" + } +} +``` + + ## See also * [Push](/docs/cli/push) — Explore all `ably push` commands.