# 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`](https://ably.com/docs/pub-sub/api/javascript/realtime/push.md). 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.

<Code>

#### Javascript

```
const admin = realtime.push.admin;
```
</Code>

## Properties

The `PushAdmin` interface has the following properties:

<Table id='PushAdminProperties'>

| Property | Description | Type |
| --- | --- | --- |
| deviceRegistrations | A [`PushDeviceRegistrations`](#device-registrations) object for registering new devices, updating existing devices, deregistering devices, and retrieving or listing devices registered to an app. | [PushDeviceRegistrations](#device-registrations) |
| channelSubscriptions | A [`PushChannelSubscriptions`](#channel-subscriptions) object for subscribing, listing, and unsubscribing individual devices or groups of [identified devices](https://ably.com/docs/auth/identified-clients.md) to push notifications published on channels. | [PushChannelSubscriptions](#channel-subscriptions) |

</Table>

## Publish a push notification 

`admin.publish(recipient: any, payload: any): Promise<void>`

Sends a push notification using [direct publishing](https://ably.com/docs/push/publish.md#direct-publishing) to individual devices or to groups of devices sharing the same `clientId`, bypassing the realtime channel subscription model.

<Code>

### Javascript

```
await realtime.push.admin.publish(
  { deviceId: '<device-id>' },
  {
    notification: {
      title: 'Hello',
      body: 'A push notification from Ably'
    }
  }
);
```
</Code>

### Parameters 

The `publish()` method takes the following parameters:

<Table id='PublishParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| recipient | Required | A JSON object identifying the recipient. Specify either `clientId`, `deviceId`, or the underlying notifications service identifiers (such as `fcmToken`, `apnsDeviceToken`). The [push publish REST API](https://ably.com/docs/api/rest-api.md#push-publish) documents the supported recipient fields. | Object |
| payload | Required | A JSON object containing the push notification payload. See the [push notification payload reference](https://ably.com/docs/push/publish.md#payload). | Object |

</Table>

### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the notification has been accepted by Ably, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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`.

<Code>

### Javascript

```
const registrations = realtime.push.admin.deviceRegistrations;
```
</Code>

### Get a device registration 

`deviceRegistrations.get(deviceId: string): Promise<DeviceDetails>`

Retrieves the [`DeviceDetails`](#DeviceDetails) of a device registered to receive push notifications using its `deviceId`.

`deviceRegistrations.get(deviceDetails: DeviceDetails): Promise<DeviceDetails>`

Retrieves the [`DeviceDetails`](#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`.

<Code>

#### Javascript

```
const device = await realtime.push.admin.deviceRegistrations.get('<device-id>');
```
</Code>

#### Parameters 

<Table id='DeviceRegistrationsGetParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| deviceId | required | The unique ID of the device to retrieve. Provide either `deviceId` or `deviceDetails`. | String |
| deviceDetails | required | A `DeviceDetails` object containing the `id` property of the device to retrieve. Provide either `deviceId` or `deviceDetails`. | <Table id='DeviceDetails'/> |

</Table>

#### Returns 

`Promise<DeviceDetails>`

Returns a promise. The promise is fulfilled with a [`DeviceDetails`](#DeviceDetails) object, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) object.

### List device registrations 

`deviceRegistrations.list(params: DeviceRegistrationParams): Promise<PaginatedResult<DeviceDetails>>`

Retrieves all devices matching the filter `params` provided. Requires `push-admin` permission.

<Code>

#### Javascript

```
const devices = await realtime.push.admin.deviceRegistrations.list({ clientId: 'user-123' });
```
</Code>

#### Parameters 

The `list()` method takes the following parameters:

<Table id='DeviceRegistrationsListParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Required | Filter parameters for the query. | <Table id='DeviceRegistrationParams'/> |

</Table>

<Table id='DeviceRegistrationParams' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| clientId | Optional | A `clientId` to filter by. Cannot be used with a `deviceId` param. | String |
| deviceId | Optional | A `deviceId` to filter by. Cannot be used with a `clientId` param. | String |
| limit | Optional | An upper limit on the number of devices returned. Default: 100. Maximum: 1000. | Number |
| state | Optional | Filter by the state of the device. Must be one of `ACTIVE`, `FAILING`, or `FAILED`. Applies to `list()` only; `removeWhere()` ignores this param. | String |

</Table>

#### Returns 

`Promise<PaginatedResult<DeviceDetails>>`

Returns a promise. The promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#PaginatedResult) of [`DeviceDetails`](#DeviceDetails) objects, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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`](#DeviceDetails) for the device. Requires `push-admin` permission, or `push-subscribe` permission together with device authentication matching the requested `deviceId`.

<Code>

#### Javascript

```
const saved = await realtime.push.admin.deviceRegistrations.save(deviceDetails);
```
</Code>

#### Parameters 

<Table id='DeviceRegistrationsSaveParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| deviceDetails | required | The `DeviceDetails` object to create or update. | <Table id='DeviceDetails'/> |

</Table>

#### Returns 

`Promise<DeviceDetails>`

Returns a promise. The promise is fulfilled with the saved [`DeviceDetails`](#DeviceDetails) object, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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`.

<Code>

#### Javascript

```
await realtime.push.admin.deviceRegistrations.remove('<device-id>');
```
</Code>

#### Parameters 

<Table id='DeviceRegistrationsRemoveParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| deviceId | required | The unique ID of the device to remove. Provide either `deviceId` or `deviceDetails`. | String |
| deviceDetails | required | A `DeviceDetails` object containing the `id` property of the device to remove. Provide either `deviceId` or `deviceDetails`. | <Table id='DeviceDetails'/> |

</Table>

#### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the registration has been removed, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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.

<Code>

#### Javascript

```
await realtime.push.admin.deviceRegistrations.removeWhere({ clientId: 'user-123' });
```
</Code>

#### Parameters 

<Table id='DeviceRegistrationsRemoveWhereParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | required | Filter parameters identifying the devices to remove. The `limit` property is ignored. | <Table id='DeviceRegistrationParams'/> |

</Table>

#### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the matching registrations have been removed, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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](https://ably.com/docs/auth/identified-clients.md). Access it via `admin.channelSubscriptions`.

<Code>

### Javascript

```
const subscriptions = realtime.push.admin.channelSubscriptions;
```
</Code>

### List channel subscriptions 

`channelSubscriptions.list(params: PushChannelSubscriptionParams): Promise<PaginatedResult<PushChannelSubscription>>`

Retrieves all push channel subscriptions matching the filter `params` provided.

<Code>

#### Javascript

```
const subs = await realtime.push.admin.channelSubscriptions.list({ channel: 'news' });
```
</Code>

#### Parameters 

The `list()` method takes the following parameters:

<Table id='ChannelSubscriptionsListParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Required | Filter parameters for the query. | <Table id='PushChannelSubscriptionParams'/> |

</Table>

<Table id='PushChannelSubscriptionParams' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| channel | Optional | The channel name to filter subscriptions by. | String |
| clientId | Optional | A `clientId` to filter subscriptions by. Cannot be used with a `deviceId` param. | String |
| deviceId | Optional | A `deviceId` to filter subscriptions by. Cannot be used with a `clientId` param. | String |
| limit | Optional | An upper limit on the number of subscriptions returned. Default: 100. Maximum: 1000. | Number |

</Table>

#### Returns 

`Promise<PaginatedResult<PushChannelSubscription>>`

Returns a promise. The promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#PaginatedResult) of `PushChannelSubscription` objects, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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](https://ably.com/docs/push/publish.md#sub-channels). Requires `push-admin` permission.

<Code>

#### Javascript

```
const channels = await realtime.push.admin.channelSubscriptions.listChannels({});
```
</Code>

#### Parameters 

The `listChannels()` method takes the following parameters:

<Table id='ListChannelsParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Required | Pagination options. | <Table id='PushChannelsParams'/> |

</Table>

<Table id='PushChannelsParams' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| limit | Optional | An upper limit on the number of channels returned. Default: 100. Maximum: 1000. | Number |

</Table>

#### Returns 

`Promise<PaginatedResult<string>>`

Returns a promise. The promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#PaginatedResult) of channel name strings, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) object.

### Save a channel subscription 

`channelSubscriptions.save(subscription: PushChannelSubscription): Promise<PushChannelSubscription>`

Subscribes a device, or group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md), to push notifications on a channel.

<Code>

#### Javascript

```
const saved = await realtime.push.admin.channelSubscriptions.save({
  channel: 'news',
  clientId: 'user-123'
});
```
</Code>

#### Parameters 

<Table id='ChannelSubscriptionsSaveParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| subscription | required | The push channel subscription to create or update. | <Table id='PushChannelSubscription'/> |

</Table>

#### Returns 

`Promise<PushChannelSubscription>`

Returns a promise. The promise is fulfilled with the newly subscribed or updated `PushChannelSubscription` object, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) object.

### Remove a channel subscription 

`channelSubscriptions.remove(subscription: PushChannelSubscription): Promise<void>`

Unsubscribes a device, or group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md), 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`.

<Code>

#### Javascript

```
await realtime.push.admin.channelSubscriptions.remove({ channel: 'news', clientId: 'user-123' });
```
</Code>

#### Parameters 

<Table id='ChannelSubscriptionsRemoveParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| subscription | required | The push channel subscription to remove. | <Table id='PushChannelSubscription'/> |

</Table>

#### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the subscription has been removed, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#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.

<Code>

#### Javascript

```
await realtime.push.admin.channelSubscriptions.removeWhere({ channel: 'news' });
```
</Code>

#### Parameters 

<Table id='ChannelSubscriptionsRemoveWhereParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | required | Filter parameters identifying the subscriptions to remove. Can contain `channel`, and optionally either `clientId` or `deviceId`. | <Table id='PushChannelSubscriptionParams'/> |

</Table>

#### Returns 

`Promise<void>`

Returns a promise. The promise is fulfilled when the matching subscriptions have been removed, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) object.

## DeviceDetails 

A `DeviceDetails` represents a device registered for push notifications.

<Table id='DeviceDetails'>

| Property | Description | Type |
| --- | --- | --- |
| id | A unique ID generated by the device. | String |
| clientId | Optional trusted [client identifier](https://ably.com/docs/auth/identified-clients.md) for the device. | String or Undefined |
| platform | The platform of the push device. One of `android`, `ios`, or `browser`. | String |
| formFactor | Form factor of the push device. One of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car`, `embedded`, or `other`. | String |
| metadata | A JSON object of key-value pairs that contains metadata for the device. The metadata for a device may only be set by clients with `push-admin` privileges. | Object or Undefined |
| deviceSecret | A unique device secret generated by the Ably SDK. | String or Undefined |
| push | Contains details about the device's push notification registration. | <Table id='DevicePushDetails'/> |

</Table>

<Table id='DevicePushDetails' >

| Property | Description | Type |
| --- | --- | --- |
| recipient | A JSON object containing the push transport and address (for example, an FCM registration token or APNs device token), as documented in the [push publish reference](https://ably.com/docs/api/rest-api.md#message-extras-push). | Object |
| state | The current state of the push device. One of `ACTIVE`, `FAILING`, or `FAILED`. | String or Undefined |
| error | When `state` is `FAILING` or `FAILED`, this contains the reason for the most recent failure. | [ErrorInfo](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) or Undefined |

</Table>

<Table id='PushChannelSubscription' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| channel | Required | The channel the push notification subscription is for. | String |
| deviceId | Optional | The unique ID of the device. Provide either `deviceId` or `clientId`. | String |
| clientId | Optional | The ID of the client the device, or devices, are associated with. Provide either `clientId` or `deviceId`. | String |

</Table>


## Related Topics

- [Push](https://ably.com/docs/pub-sub/api/javascript/realtime/push.md): API reference for the Push interface in the Ably Pub/Sub JavaScript Realtime SDK.
- [PushChannel](https://ably.com/docs/pub-sub/api/javascript/realtime/push-channel.md): API reference for the PushChannel interface in the Ably Pub/Sub JavaScript Realtime SDK.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.