Push publish

Use the ably push publish command to publish a push notification to a device, client, or channel.

Synopsis

ably push publish [options]

Options

--device-id

The ID of the device to publish to. Exclusive with --client-id and --recipient.

--client-id

The client ID to publish to. Exclusive with --device-id and --recipient.

--recipient

A raw JSON recipient object. Exclusive with --device-id and --client-id.

--channel

The target channel name. Publishes a push notification via the channel using extras.push. Ignored if --device-id, --client-id, or --recipient is also provided. Use together with --message to publish a realtime message on the channel alongside the push notification.

--message

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

The title of the push notification.

--body

The body text of the push notification.

--sound

The sound to play when the notification is received.

--icon

The icon for the push notification.

--badge

The badge number to display on the app icon.

--data

A JSON payload to include with the push notification.

--collapse-key

A collapse key for grouping notifications.

--ttl

The time-to-live for the notification in seconds.

--payload

A full JSON payload for the push notification, provided as a JSON string or a file path. Overrides convenience options such as --title and --body.

--apns

APNs-specific JSON configuration.

--fcm

FCM-specific JSON configuration.

--web

Web push-specific JSON configuration.

--force | -f

Skip confirmation prompt. Required when using --json. The default is false.

--json

Output results as compact JSON. Mutually exclusive with --pretty-json.

--pretty-json

Output results in formatted JSON. Mutually exclusive with --json.

--verbose | -v

Enable verbose logging. Can be combined with --json or --pretty-json.

Examples

Publish to a device:

ably push publish --device-id "device123" --title "Hello" --body "World"

Publish to a client:

ably push publish --client-id "user456" --title "Update" --body "New content available"

Publish to a channel:

ably push publish --channel "announcements" --title "News" --body "Breaking update" --message "Breaking update" --force

Publish to a device with a custom payload:

ably push publish --device-id "device123" --payload '{"notification":{"title":"Custom","body":"Payload"},"data":{"key":"value"}}'

Publish to a device with additional data:

ably push publish --device-id device-123 --title Hello --body World --data '{"key":"value"}'

Publish to a device using a JSON payload string:

ably push publish --device-id device-123 --payload '{"notification":{"title":"Hello","body":"World"}}'

Publish to a device using a payload from a file:

ably push publish --device-id device-123 --payload ./notification.json

See notification file example below.

Publish to a client using a JSON payload string:

ably push publish --client-id client-1 --payload '{"notification":{"title":"Hello","body":"World"}}'

Publish to a channel with a message string and additional data:

ably push publish --channel my-channel --title Hello --body World --data '{"key":"value"}' --message 'Hello from push'

Publish to a channel using a JSON payload string:

ably push publish --channel my-channel --payload '{"notification":{"title":"Hello","body":"World"},"data":{"key":"value"}}' --message 'Hello from push'

Publish to a channel with a message JSON object (a full message object with name and data fields):

ably push publish --channel my-channel --title Hello --body World --message '{"name":"greeting","data":"Welcome back"}'

Publish to a channel with a message data JSON payload (a JSON object containing arbitrary message data fields):

ably push publish --channel my-channel --title Hello --body World --message '{"event":"push","text":"Hello"}'

Publish to a channel using a payload from a file and a string message:

ably push publish --channel my-channel --payload ./notification.json --message 'Hello from push'

See notification file example below.

Publish using raw recipient attributes:

ably push publish --recipient '{"transportType":"apns","deviceToken":"token123"}' --title Hello --body World

Publish and output in JSON format:

ably push publish --device-id device-123 --title Hello --body World --json

Notification.json file

{
  "notification": {
    "title": "Hello",
    "body": "World"
  },
  "data": {
    "key": "value"
  }
}

See also

• Push — Explore all ably push commands.
• CLI reference — Full list of available commands.