PushAdmin
The PushAdmin interface provides server-side and admin-level operations for managing push notifications across devices and channels. Access it via realtime.push.admin. Most PushAdmin operations require the push-admin capability. The per-device operations get, save, and remove can alternatively be performed with the push-subscribe capability together with device authentication matching the requested deviceId. Required capabilities are noted on each method below.
1
const admin = realtime.push.admin;Properties
The PushAdmin interface has the following properties:
deviceRegistrationsPushDeviceRegistrationsPushDeviceRegistrations object for registering new devices, updating existing devices, deregistering devices, and retrieving or listing devices registered to an app.channelSubscriptionsPushChannelSubscriptionsPushChannelSubscriptions object for subscribing, listing, and unsubscribing individual devices or groups of identified devices to push notifications published on channels.Publish a push notification
admin.publish(recipient: any, payload: any): Promise<void>Sends a push notification using direct publishing to individual devices or to groups of devices sharing the same clientId, bypassing the realtime channel subscription model.
1
2
3
4
5
6
7
8
9
await realtime.push.admin.publish(
{ deviceId: '<device-id>' },
{
notification: {
title: 'Hello',
body: 'A push notification from Ably'
}
}
);Parameters
The publish() method takes the following parameters:
recipientrequiredObjectclientId, deviceId, or the underlying notifications service identifiers (such as fcmToken, apnsDeviceToken). The push publish REST API documents the supported recipient fields.payloadrequiredObjectReturns
Promise<void>
Returns a promise. The promise is fulfilled when the notification has been accepted by Ably, or rejected with an ErrorInfo object.
PushDeviceRegistrations
Registers new devices, updates existing devices, deregisters devices, and retrieves or lists devices registered to an app. Access it via admin.deviceRegistrations.
1
const registrations = realtime.push.admin.deviceRegistrations;Get a device registration
deviceRegistrations.get(deviceId: string): Promise<DeviceDetails>Retrieves the DeviceDetails of a device registered to receive push notifications using its deviceId.
deviceRegistrations.get(deviceDetails: DeviceDetails): Promise<DeviceDetails>Retrieves the DeviceDetails of a device registered to receive push notifications using the id property of an existing DeviceDetails object.
Requires push-admin permission, or push-subscribe permission together with device authentication matching the requested deviceId.
1
const device = await realtime.push.admin.deviceRegistrations.get('<device-id>');Parameters
deviceIdrequiredStringdeviceId or deviceDetails.deviceDetailsrequiredDeviceDetailsDeviceDetails object containing the id property of the device to retrieve. Provide either deviceId or deviceDetails.Returns
Promise<DeviceDetails>
Returns a promise. The promise is fulfilled with a DeviceDetails object, or rejected with an ErrorInfo object.
List device registrations
deviceRegistrations.list(params: DeviceRegistrationParams): Promise<PaginatedResult<DeviceDetails>>Retrieves all devices matching the filter params provided. Requires push-admin permission.
1
const devices = await realtime.push.admin.deviceRegistrations.list({ clientId: 'user-123' });Parameters
The list() method takes the following parameters:
paramsrequiredDeviceRegistrationParamsReturns
Promise<PaginatedResult<DeviceDetails>>
Returns a promise. The promise is fulfilled with a PaginatedResult of DeviceDetails objects, or rejected with an ErrorInfo object.
Save a device registration
deviceRegistrations.save(deviceDetails: DeviceDetails): Promise<DeviceDetails>Registers or updates a device with Ably for push notifications. Stores or updates the DeviceDetails for the device. Requires push-admin permission, or push-subscribe permission together with device authentication matching the requested deviceId.
1
const saved = await realtime.push.admin.deviceRegistrations.save(deviceDetails);Parameters
deviceDetailsrequiredDeviceDetailsDeviceDetails object to create or update.Returns
Promise<DeviceDetails>
Returns a promise. The promise is fulfilled with the saved DeviceDetails object, or rejected with an ErrorInfo object.
Remove a device registration
deviceRegistrations.remove(deviceId: string): Promise<void>Removes a device registered to receive push notifications from Ably using its deviceId.
deviceRegistrations.remove(deviceDetails: DeviceDetails): Promise<void>Removes a device registered to receive push notifications from Ably using the id property of a DeviceDetails object.
Requires push-admin permission, or push-subscribe permission together with device authentication matching the requested deviceId.
1
await realtime.push.admin.deviceRegistrations.remove('<device-id>');Parameters
deviceIdrequiredStringdeviceId or deviceDetails.deviceDetailsrequiredDeviceDetailsDeviceDetails object containing the id property of the device to remove. Provide either deviceId or deviceDetails.Returns
Promise<void>
Returns a promise. The promise is fulfilled when the registration has been removed, or rejected with an ErrorInfo object. A request to delete a device that does not exist results in a successful operation.
Remove device registrations matching params
deviceRegistrations.removeWhere(params: DeviceRegistrationParams): Promise<void>Removes all devices matching the filter params provided. The limit property is ignored. Requires push-admin permission.
1
await realtime.push.admin.deviceRegistrations.removeWhere({ clientId: 'user-123' });Parameters
paramsrequiredDeviceRegistrationParamslimit property is ignored.Returns
Promise<void>
Returns a promise. The promise is fulfilled when the matching registrations have been removed, or rejected with an ErrorInfo object. A request that does not match any existing devices still results in a successful operation.
PushChannelSubscriptions
Subscribes a push notification device to a channel, ensuring the device receives any push notifications published in the future on that channel. It also allows these subscriptions to be retrieved, listed, updated, or removed for individual devices or groups of identified devices. Access it via admin.channelSubscriptions.
1
const subscriptions = realtime.push.admin.channelSubscriptions;List channel subscriptions
channelSubscriptions.list(params: PushChannelSubscriptionParams): Promise<PaginatedResult<PushChannelSubscription>>Retrieves all push channel subscriptions matching the filter params provided.
1
const subs = await realtime.push.admin.channelSubscriptions.list({ channel: 'news' });Parameters
The list() method takes the following parameters:
paramsrequiredPushChannelSubscriptionParamsReturns
Promise<PaginatedResult<PushChannelSubscription>>
Returns a promise. The promise is fulfilled with a PaginatedResult of PushChannelSubscription objects, or rejected with an ErrorInfo object.
List channels with subscriptions
channelSubscriptions.listChannels(params: PushChannelsParams): Promise<PaginatedResult<string>>Retrieves all channels with at least one device subscribed to push notifications. Requires push-admin permission.
1
const channels = await realtime.push.admin.channelSubscriptions.listChannels({});Parameters
The listChannels() method takes the following parameters:
paramsrequiredPushChannelsParamsReturns
Promise<PaginatedResult<string>>
Returns a promise. The promise is fulfilled with a PaginatedResult of channel name strings, or rejected with an ErrorInfo object.
Save a channel subscription
channelSubscriptions.save(subscription: PushChannelSubscription): Promise<PushChannelSubscription>Subscribes a device, or group of devices sharing a client identifier, to push notifications on a channel.
1
2
3
4
const saved = await realtime.push.admin.channelSubscriptions.save({
channel: 'news',
clientId: 'user-123'
});Parameters
subscriptionrequiredPushChannelSubscriptionReturns
Promise<PushChannelSubscription>
Returns a promise. The promise is fulfilled with the newly subscribed or updated PushChannelSubscription object, or rejected with an ErrorInfo object.
Remove a channel subscription
channelSubscriptions.remove(subscription: PushChannelSubscription): Promise<void>Unsubscribes a device, or group of devices sharing a client identifier, from receiving push notifications on a channel. Requires push-admin permission, or, for a subscription associated with a given deviceId, push-subscribe permission together with device authentication matching that deviceId.
1
await realtime.push.admin.channelSubscriptions.remove({ channel: 'news', clientId: 'user-123' });Parameters
subscriptionrequiredPushChannelSubscriptionReturns
Promise<void>
Returns a promise. The promise is fulfilled when the subscription has been removed, or rejected with an ErrorInfo object.
Remove channel subscriptions matching params
channelSubscriptions.removeWhere(params: PushChannelSubscriptionParams): Promise<void>Unsubscribes all devices matching the filter params provided from push notifications on a channel. Requires push-admin permission.
1
await realtime.push.admin.channelSubscriptions.removeWhere({ channel: 'news' });Parameters
paramsrequiredPushChannelSubscriptionParamschannel, and optionally either clientId or deviceId.Returns
Promise<void>
Returns a promise. The promise is fulfilled when the matching subscriptions have been removed, or rejected with an ErrorInfo object.
DeviceDetails
A DeviceDetails represents a device registered for push notifications.
idStringclientIdString or UndefinedplatformStringandroid, ios, or browser.formFactorStringphone, tablet, desktop, tv, watch, car, embedded, or other.metadataObject or Undefinedpush-admin privileges.deviceSecretString or UndefinedpushDevicePushDetails