Push Notifications - Admin

This object is accessible through client.push.admin and provides:

The push admin object exposes the following public properties:

The returned DeviceRegistrations object provides functionality for registering, updating, listing and de-registering push devices.

The returned PushChannelSubscriptions object provides functionality for subscribing, listing and unsubscribing individual devices or groups of identified devices to push notifications published on channels.

publish(Object recipient, Object payload): Promise<void>

Publishes a push notification directly to a device or group of devices sharing a client identifier. See the push notification direct publishing documentation for more information.

Parameters

recipient
an object containing the push recipient details. See the push notification publish REST API documentation for details on the supported recipient fields
payload
an object containing the push notification data. See the push admin payload structure for details on the supported push payload fields

Returns

Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

This object is accessible through client.push.admin.deviceRegistrations and provides an API to register new push notification devices, update existing devices, deregister old devices, and retrieve or list devices registered to an app.

get(String deviceId): Promise<DeviceDetails>

get(DeviceDetails deviceDetails): Promise<DeviceDetails>

Obtain the DeviceDetails for a device registered for receiving push registrations matching the deviceId argument, or the id attribute of the provided DeviceDetails object. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

deviceId
the unique device ID String for the requested device
deviceDetails
a DeviceDetails object containing at a minimum the deviceId of the requested device

Returns

Returns a promise. On success, the promise is fulfilled with a DeviceDetails object representing the device registered for push notifications. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

list(Object params): Promise<PaginatedResult<DeviceDetails>>

Retrieve all devices matching the params filter as a paginated list of DeviceDetails objects. Requires push-admin permission.

Parameters

params
an object containing the query parameters as key value pairs as specified below.

params properties

clientId
optional filter to restrict to devices associated with that client identifier. Cannot be used with a deviceId paramType: String
deviceId
optional filter to restrict to devices associated with that device identifier. Cannot be used with a clientId paramType: String
limit
100 maximum number of devices per page to retrieve, up to 1,000Type: Integer
state
optional filter by the state of the device. Must be one of ACTIVE, FAILING or FAILED Type: String

Returns

Returns a promise. On success, the promise is fulfilled with a PaginatedResult encapsulating an array of DeviceDetails objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

save(DeviceDetails deviceDetails): Promise<DeviceDetails>

Register a new DeviceDetails object, or update an existing DeviceDetails object with the Ably service. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

deviceDetails
a DeviceDetails object

Returns

Returns a promise. On success, the promise is fulfilled with a DeviceDetails object representing the newly registered or updated device. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

remove(String deviceId): Promise<void>

remove(DeviceDetails deviceDetails): Promise<void>

Remove a device registered for receiving push registrations that matches the deviceId argument, or the id attribute of the provided DeviceDetails object. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

deviceId
the unique device ID String for the device
deviceDetails
a DeviceDetails object containing at a minimum the deviceId of the device

Returns

Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

removeWhere(Object params): Promise<void>

Delete all devices matching the params filter. Requires push-admin permission.

Parameters

params
an object containing the filter parameters as key value pairs as specified below.

params properties

clientId
optional filter to restrict to devices associated with that client identifier. Cannot be used with a deviceId paramType: String
deviceId
optional filter to restrict to devices associated with that device identifier. Cannot be used with a clientId paramType: String

Returns

Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

This object is accessible through client.push.admin.channelSubscriptions and provides an API to subscribe a push notification device to a channel ensuring it receives any push notifications published in the future on that channel. Additionally, this object allows these subscriptions to be retrieved, listed, updated or removed.

list(Object params): Promise<PaginatedResult<PushChannelSubscription>>

Retrieve all push channel subscriptions that match the provided params filter as a paginated list of PushChannelSubscription objects. Each PushChannelSubscription represents a device or set of devices sharing the same client identifier registered to a channel to receive push notifications.

Parameters

params
an object containing the query parameters as key value pairs as specified below.

params properties

channel
filter to restrict to subscriptions associated with that channel
clientId
optional filter to restrict to devices associated with that client identifier. Cannot be used with a deviceId paramType: String
deviceId
optional filter to restrict to devices associated with that device identifier. Cannot be used with a clientId paramType: String
limit
100 maximum number of channel subscriptions per page to retrieve, up to 1,000Type: Integer

Returns

Returns a promise. On success, the promise is fulfilled with a PaginatedResult encapsulating an array of PushChannelSubscription objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

listChannels(Object params): Promise<PaginatedResult<String>>

Retrieve a list of channels that have at least one device subscribed to push notifications as a paginated list of channel name String objects. Requires push-admin permission.

Parameters

params
an object containing the query parameters as key value pairs as specified below.

params properties

limit
100 maximum number of channels per page to retrieve, up to 1,000Type: Integer

Returns

Returns a promise. On success, the promise is fulfilled with a PaginatedResult encapsulating an array of channel name String values corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

save(PushChannelSubscription subscription): Promise<PushChannelSubscription>

Subscribe a device or group of devices sharing a client identifier for push notifications published on a channel.

Parameters

subscription
a PushChannelSubscription object

Returns

Returns a promise. On success, the promise is fulfilled with a PushChannelSubscription object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

remove(PushChannelSubscription subscription): Promise<void>

Unsubscribe a device or group of devices sharing a client identifier from push notifications on a channel. Requires push-admin permission or, in the case of a subscription associated with a given deviceId, push-subscribe permission together with device authentication matching that deviceId.

Parameters

subscription
a PushChannelSubscription object

Returns

Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

removeWhere(Object params): Promise<void>

Delete all push channel subscriptions matching the params filter. Requires push-admin permission.

Parameters

params
an object containing the filter parameters as key value pairs as specified below.

params properties

channel
filter to restrict to subscriptions associated with that channel
clientId
optional filter to restrict to devices associated with that client identifier. Cannot be used with deviceId paramType: String
deviceId
optional filter to restrict to devices associated with that device identifier. Cannot be used with clientId paramType: String

Returns

Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.

Properties

id
unique identifier for the device generated by the device itselfType: String
clientId
optional trusted client identifier for the deviceType: String
formFactor
form factor of the push device. Must be one of phone, tablet, desktop, tv, watch, car embedded or otherType: String
metadata
optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privilegesType: Object
platform
platform of the push device. Must be one of ios android or browserType: String
deviceSecret
Secret value for the device.Type: String
push.recipient
push recipient details for this device. See the REST API push publish documentation for more detailsType: Object
push.state
the current state of the push device being either ACTIVE, FAILING or FAILEDType: String
push.error
when the device’s state is failing or failed, this attribute contains the reason for the most recent failureType: ErrorInfo

A PushChannel is a property of a RealtimeChannel or RestChannel. It provides push devices the ability to subscribe and unsubscribe to push notifications on channels.

Methods

subscribeDevice(): Promise<void>

Subscribe your device to the channel’s push notifications.

Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

subscribeClient(): Promise<void>

Subscribe all devices associated with your device’s clientId to the channel’s push notifications.

Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

unsubscribeDevice(): Promise<void>

Unsubscribe your device from the channel’s push notifications.

Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

unsubscribeClient(): Promise<void>

Unsubscribe all devices associated with your device’s clientId from the channel’s push notifications.

Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

listSubscriptions(Record<string, string> params?): Promise<PaginatedResult<PushChannelSubscription>>;

Lists push subscriptions on a channel specified by its channel name (channel). These subscriptions can be either be a list of client (clientId) subscriptions, device (deviceId) subscriptions, or if concatFilters is set to true, a list of both. This method requires clients to have the Push Admin capability. For more information, see GET rest.ably.io/push/channelSubscriptions Rest API.

Parameters

deviceId
a deviceId to filter byType: String
clientId
a clientId to filter byType: String
deviceClientId
a client ID associated with a device to filter byType: String
params
An optional object containing key-value pairs to filter subscriptions by. Can contain clientId, deviceId or a combination of both, and a limit on the number of subscriptions returned, up to 1,000Type: Record<string, string>

Returns

Returns a promise. On success, the promise is fulfilled with PaginatedResult which encapsulates an array of PushChannelSubscription objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

An PushChannelSubscription is a type encapsulating the subscription of a device or group of devices sharing a client identifier to a channel in order to receive push notifications.

Properties

channel
the channel that this push notification subscription is associated withType: String
deviceId
the device with this identifier is linked to this channel subscription. When present, clientId is never presentType: String
clientId
devices with this client identifier are included in this channel subscription. When present, deviceId is never presentType: String

A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.

Properties

Methods

first(): Promise<PaginatedResult>

Returns a promise. On success, the promise is fulfilled with a new PaginatedResult for the first page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

Boolean hasNext()

Returns true if there are more pages available by calling next and returns false if this page is the last page available.

Boolean isLast()

Returns true if this page is the last page and returns false if there are more pages available by calling next available.

next(): Promise<PaginatedResult | null>

Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

current(): Promise<PaginatedResult>

Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the current page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.

JavaScript v2.9
const paginatedResult = await channel.history(); console.log('Page 0 item 0:' + paginatedResult.items[0].data); const nextPage = await paginatedResult.next(); console.log('Page 1 item 1: ' + nextPage.items[1].data); console.log('Last page?: ' + nextPage.isLast());
Copied!
Select...