# Push Notifications - Admin

## Push Admin object 

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

### <If lang="javascript,nodejs,java,swift,objc,python">Push Admin Properties</If><If lang="ruby">Push::Admin Properties</If> 

The push admin object exposes the following public <If lang="javascript,nodejs,python,objc,swift">properties</If><If lang="ruby">attributes</If><If lang="java">members</If>:

#### <If lang="javascript,nodejs,java,objc,swift">deviceRegistrations</If><If lang="python,ruby">device_registrations</If> 

The returned [`DeviceRegistrations`](#device-registrations-object) object provides functionality for registering, updating, listing and de-registering push devices.

#### <If lang="javascript,nodejs,java,objc,swift">channelSubscriptions</If><If lang="python,ruby">channel_subscriptions</If> 

The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality 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.

### Methods 

#### publish 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`Deferrable publish(Hash recipient, Hash data) → yield`

</If>
<If lang="python">

`publish(recipient=Object, data=Object)`

</If>
<If lang="objc,swift">

`publish(recipient: ARTPushRecipient, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="java">

`void publish(String recipient, Object data, CompletionListener listener)`

</If>

Publishes a push notification directly to a device or group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md). See the [push notification direct publishing documentation](https://ably.com/docs/push/publish.md#direct-publishing) for more information.

##### Parameters

<If lang="javascript,nodejs,python">

| Parameter | Description | Type |
|-----------|------|-------------|
| recipient | Contains the push recipient details. See the [push notification publish REST API documentation](https://ably.com/docs/api/rest-api.md#push-publish) for details on the supported recipient fields | `Object` |
| <If lang="javascript,nodejs">payload</If><If lang="python">data</If> | Contains the push notification data. See the [push admin payload structure](https://ably.com/docs/push/publish.md#payload) for details on the supported push payload fields | `Object` |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| recipient | Contains the push recipient details. See the [push notification publish REST API documentation](https://ably.com/docs/api/rest-api.md#push-publish) for details on the supported recipient fields | `Hash` |
| data | Contains the push notification data. See the [push admin payload structure](https://ably.com/docs/push/publish.md#payload) for details on the supported push payload fields | `Hash` |
| &block | Yielded upon success | |

</If>

<If lang="java">

| Parameter | Description | Type |
|-----------|------|-------------|
| recipient | Contains the push recipient details. See the [push notification publish REST API documentation](https://ably.com/docs/api/rest-api.md#push-publish) for details on the supported recipient fields | `Object` |
| data | Contains the push notification data. See the [push admin payload structure](https://ably.com/docs/push/publish.md#payload) for details on the supported push payload fields | `Object` |
| listener | Listener to be notified on completion | [`CompletionListener`](#completion-listener) |

</If>

<If lang="objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| recipient | Contains the push recipient details. See the [push notification publish REST API documentation](https://ably.com/docs/api/rest-api.md#push-publish) for details on the supported recipient fields | `Object` |
| data | Contains the push notification data. See the [push admin payload structure](https://ably.com/docs/push/publish.md#payload) for details on the supported push payload fields | `Object` |
| callback | Called upon publishing the message, or with an error | |

</If>

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

The callback is called upon success or failure to publish the push notification. When this operation fails, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method are yielded to.

Failure to publish the push notification will trigger the `errback` callback of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="java">

##### Listener result

On successful publish of the message, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to publish the message, the `onError` method is called with an [`ErrorInfo`](#error-info) argument describing the failure reason.

</If>

## <If lang="javascript,nodejs">PushDeviceRegistrations object</If><If lang="java,python,objc,swift,ruby">DeviceRegistrations object</If> 

This object is accessible through <If lang="javascript,nodejs,java,python,objc,swift">`client.push.admin.deviceRegistrations`</If><If lang="ruby">`client.push.admin.device_registrations`</If> 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.

### Methods 

#### get 

<If lang="javascript,nodejs">

`get(String deviceId): Promise<DeviceDetails>`

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

</If>
<If lang="ruby">

`get(String deviceId) -> yields DeviceDetails`

`get(DeviceDetails device) -> yields DeviceDetails`

</If>
<If lang="python">

`DeviceDetails get(device_id=String)`

`get(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))`

</If>
<If lang="objc,swift">

`get(deviceId: ArtDeviceId, callback: ((ARTDeviceDetails?, ARTErrorInfo?) -> Void))`

`get(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))`

</If>
<If lang="java">

`DeviceDetails get(String deviceId)`

`getAsync(String deviceId, Callback<DeviceDetails> callback)`

`get(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))`

</If>

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

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | The unique device ID String for the requested device | `String` |
| <If lang="javascript,nodejs">deviceDetails</If><If lang="java,python,objc,swift">device</If> | A `DeviceDetails` object containing at a minimum the `deviceId` of the requested device | [`DeviceDetails`](#device-details) |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | The unique device ID String for the requested device | `String` |
| device | A `DeviceDetails` object containing at a minimum the `deviceId` of the requested device | [`DeviceDetails`](#device-details) |
| &block | Yields a `DeviceDetails` object upon success | |

</If>

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the device registered for push notifications. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

On success, `device` contains the device registered for push notifications as a [`DeviceDetails`](#device-details) object.

On failure to retrieve the device, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method yield the device registered for push notifications as a [`DeviceDetails`](#device-details) object.

Failure to retrieve the device will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="java">

##### Listener result

On successful publish of the message, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to get the device, the `onError` method is called with an [`ErrorInfo`](#error-info) argument describing the failure reason.

</If>

#### list 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`Deferrable list(Hash params) → yields PaginatedResult<DeviceDetails>`

</If>
<If lang="python">

`PaginatedResult list(params=Object)`

</If>
<If lang="objc,swift">

`list(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) -> Void))`

</If>

<If lang="java">

`PaginatedResult list(Param[] params)`

</If>

Retrieve all devices matching the params filter as a paginated list of [`DeviceDetails`](#device-details) objects. Requires `push-admin` permission.

##### Parameters

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | <If lang="javascript,nodejs,python,objc,swift">`Object`</If><If lang="java">[`Param[]`](#param)</If> |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | `Object` |
| &block | | Yields a `PaginatedResult<DeviceDetails>` object |

</If>

##### `params` properties

<If lang="java,python,objc,swift,ruby">

| Property | Description | Type |
|----------|------|-------------|
| <If lang="java,python,objc,swift">clientId</If><If lang="ruby">:client_id</If> | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a <If lang="java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> param | `String` |
| <If lang="java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a <If lang="java,python,objc,swift">`clientId`</If><If lang="ruby">`:client_id`</If> param | `String` |
| <If lang="java,python,objc,swift">limit</If><If lang="ruby">:limit</If> | _100_ maximum number of devices per page to retrieve, up to 1,000 | `Integer` |

</If>

<If lang="javascript,nodejs">

| Property | Description | Type |
|----------|------|-------------|
| clientId | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId` param | `String` |
| deviceId | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId` param | `String` |
| limit | _100_ maximum number of devices per page to retrieve, up to 1,000 | `Integer` |
| state | Optional filter by the state of the device. Must be one of `ACTIVE`, `FAILING` or `FAILED` | `String` |

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of [`DeviceDetails`](#device-details) objects corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

<If lang="objc,swift">

##### Callback result

On success, `resultPage` contains a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of [`DeviceDetails`](#device-details) objects corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure to retrieve the devices, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method yield a [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) that encapsulates an array of [`DeviceDetails`](#device-details) corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

Failure to retrieve the devices will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### save 

<If lang="javascript,nodejs">

`save(DeviceDetails deviceDetails): Promise<DeviceDetails>`

</If>
<If lang="ruby">

`Deferrable save(DeviceDetails device) → yields DeviceDetails`

</If>
<If lang="python">

`DeviceDetails save(DeviceDetails device_details)`

</If>
<If lang="objc,swift">

`save(deviceDetails: DeviceDetails, callback: ((DeviceDetails?, ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`DeviceDetails save(DeviceDetails deviceDetails)`

</If>

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

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| <If lang="javascript,nodejs">deviceDetails</If><If lang="java,python,objc,swift">device</If> | A `DeviceDetails` object | [`DeviceDetails`](#device-details) |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| `device` | A `DeviceDetails` object | [`DeviceDetails`](#device-details) |
| `&block` | Yields the new `DeviceDetails` object upon success | |

</If>

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the newly registered or updated device. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

On success, `device` contains the newly registered or updated device as a [`DeviceDetails`](#device-details) object.

On failure to create or update the device, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method yield the newly registered or updated device as a [`DeviceDetails`](#device-details) object.

Failure to create or update the device will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### remove 

<If lang="javascript,nodejs">

`remove(String deviceId): Promise<void>`

`remove(DeviceDetails deviceDetails): Promise<void>`

</If>
<If lang="ruby">

`remove(String deviceId)`

`remove(DeviceDetails device) -> yield`

</If>
<If lang="python">

`remove(String device_id)`

`remove(DeviceDetails device_details)`

</If>
<If lang="objc,swift">

`remove(deviceDetails: DeviceDetails, callback: ((DeviceDetails?, ARTErrorInfo?) -> Void))`

`remove(deviceDetails: DeviceDetails, callback: ((ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`DeviceDetails save(DeviceDetails deviceDetails)`

`DeviceDetails save(DeviceDetails deviceDetails)`

</If>

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

##### Parameters

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | The unique device ID String for the device | `String` |
| <If lang="javascript,nodejs">deviceDetails</If><If lang="java,python,objc,swift">device</If> | A `DeviceDetails` object containing at a minimum the `deviceId` of the device | [`DeviceDetails`](#device-details) |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | The unique device ID String for the device | `String` |
| device | A `DeviceDetails` object containing at a minimum the `deviceId` of the device | [`DeviceDetails`](#device-details) |
| &block | Yields upon success  | |

</If>

<If lang="javascript,nodejs">

##### 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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

The callback is called upon success or failure to delete the device. Note that a request to delete a device that does not exist will result in a successful operation.

When this operation fails, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method are yielded to. Note that a request to delete a device that does not exist will result in a successful operation.

Failure to delete the device will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### <If lang="javascript,nodejs,java,objc,swift">removeWhere</If><If lang="python,ruby">remove_where</If>  

<If lang="javascript,nodejs">

`removeWhere(Object params): Promise<void>`

</If>
<If lang="ruby">

`remove_where(Hash params) -> yield`

</If>
<If lang="python">

`remove_where(params=Object)`

</If>
<If lang="objc,swift">

`removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)`

</If>
<If lang="java">

`removeWhere(Param[] params)`

</If>

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

##### Parameters

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the filter parameters as key value pairs as specified below | <If lang="javascript,nodejs,python,objc,swift">`Object`</If><If lang="java">[`Param[]`](#param)</If> |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the filter parameters as key value pairs as specified below | `Object` |
| &block | Yields upon success | |

</If>

##### `params` properties

| Property | Description | Type |
|----------|------|-------------|
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">:client_id</If> | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a <If lang="javascript,nodejs,java,python,objc,swift">`deviceId`</If><If lang="ruby">`:device_id`</If> param | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a <If lang="javascript,nodejs,java,python,objc,swift">`clientId`</If><If lang="ruby">`:client_id`</If> param | `String` |

<If lang="javascript,nodejs">

##### 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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

The callback is called upon success or failure to delete the device. Note that a request that does match any existing devices will result in a successful operation.

When this operation fails, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method are yielded to. Note that a request that does match any existing devices will result in a successful operation.

Failure to delete the device will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

## PushChannelSubscriptions object 

This object is accessible through <If lang="javascript,nodejs,java,python,objc,swift">`client.push.admin.channelSubscriptions`</If><If lang="ruby">`client.push.admin.channel_subscriptions`</If> 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.

### Methods 

#### list 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`Deferrable list(Hash params) -> yields PaginatedResult<PushChannelSubscription>`

</If>
<If lang="python">

`PaginatedResult list(params=Object)`

</If>
<If lang="objc,swift">

`list(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`PaginatedResult list(Param[] params)`

</If>

Retrieve all push channel subscriptions that match the provided params filter as a paginated list of [`PushChannelSubscription`](#push-channel-subscription) objects. Each [`PushChannelSubscription`](#push-channel-subscription) represents a device or set of devices sharing the same [client identifier](https://ably.com/docs/auth/identified-clients.md) registered to a channel to receive push notifications.

##### Parameters

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | <If lang="javascript,nodejs,python,objc,swift">`Object`</If><If lang="java">[`Param[]`](#param)</If> |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | `Object` |
| &block | Yields a `PaginatedResult<PushChannelSubscription>` object  | |

</If>

##### `params` properties

| Property | Description | Type |
|----------|------|-------------|
| <If lang="javascript,nodejs,java,python,objc,swift">channel</If><If lang="ruby">:channel</If> | Filter to restrict to subscriptions associated with that `channel` | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">:client_id</If> | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> param | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">:client_id</If> param | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">limit</If><If lang="ruby">:limit</If> | _100_ maximum number of channel subscriptions per page to retrieve, up to 1,000 | `Integer` |

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of [`PushChannelSubscription`](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

On success, `resultPage` contains a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of [`PushChannelSubscription`](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure to retrieve the channel subscriptions, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object which contains the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method yield a [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) that encapsulates an array of [`PushChannelSubscription`](#push-channel-subscription) corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

Failure to retrieve the channel subscriptions will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### <If lang="javascript,nodejs,java,objc,swift">listChannels</If><If lang="python,ruby">list_channels</If> 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`Deferrable list_channels(Hash params) -> yields PaginatedResult<String>`

</If>
<If lang="python">

`PaginatedResult list_channels(params=Object)`

</If>
<If lang="objc,swift">

`listChannels(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`PaginatedResult listChannels(Param[] params)`

</If>

Retrieve a list of channels that have at least one device [subscribed to push notifications](https://ably.com/docs/push/publish.md#sub-channels) as a paginated list of channel name `String` objects. Requires `push-admin` permission.

##### Parameters

<If lang="javascript,nodejs,java,python,objc,swift">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | <If lang="javascript,nodejs,python,objc,swift">`Object`</If><If lang="java">[`Param[]`](#param)</If> |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the query parameters as key value pairs as specified below | `Object` |
| &block | Yields a `PaginatedResult<String>` object | |

</If>

##### `params` properties

| Property | Description | Type |
|----------|------|-------------|
| <If lang="javascript,nodejs,java,python,objc,swift">limit</If><If lang="ruby">:limit</If> | _100_ maximum number of channels per page to retrieve, up to 1,000 | `Integer` |

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of channel name `String` values corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

On success, `resultPage` contains a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) encapsulating an array of channel name `String` values corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

On failure to retrieve the channels, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="ruby">

##### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from the method.

On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to the method yield a [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) that encapsulates an array of channel name `String` values corresponding to the current page of results. [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) supports pagination using [`next()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) and [`first()`](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) methods.

Failure to retrieve the channels will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### save 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`save(PushChannelSubscription channel_subscription)`

</If>
<If lang="python">

`PushChannelSubscription save(PushChannelSubscription channel_subscription)`

</If>
<If lang="objc,swift">

`save(channelSubscription: PushChannelSubscription, callback: ((PushChannelSubscription?, ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`PushChannelSubscription save(PushChannelSubscription channelSubscription)`

</If>

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

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| <If lang="java,objc,swift">channelSubscription</If><If lang="javascript,nodejs">subscription</If><If lang="ruby,python">channel_subscription</If> | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) |

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with a [`PushChannelSubscription`](#push-channel-subscription) object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

On success, `channelSubscription` contains the newly subscribed or updated push channel subscription as a [`PushChannelSubscription`](#push-channel-subscription) object.

On failure to create or update the channel subscription, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### remove 

<If lang="javascript,nodejs">

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

</If>
<If lang="ruby">

`remove(PushChannelSubscription channel_subscription)`

</If>
<If lang="python">

`remove(PushChannelSubscription channel_subscription)`

</If>
<If lang="objc,swift">

`remove(channelSubscription: PushChannelSubscription, callback: ((ARTErrorInfo?) -> Void))`

</If>
<If lang="java">

`void remove(PushChannelSubscription channelSubscription)`

</If>

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

| Parameter | Description | Type |
|-----------|------|-------------|
| <If lang="java,objc,swift">channelSubscription</If><If lang="javascript,nodejs">subscription</If><If lang="ruby,python">`channel_subscription`</If> | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) |

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

When this operation fails, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

#### <If lang="javascript,nodejs,java,objc,swift">removeWhere</If><If lang="python,ruby">remove_where</If> 

<If lang="javascript,nodejs">

`removeWhere(Object params): Promise<void>`

</If>
<If lang="ruby">

`remove_where(Hash params)`

</If>
<If lang="python">

`remove_where(params=Object)`

</If>
<If lang="objc,swift">

`removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)`

</If>
<If lang="java">

`removeWhere(Param[] params)`

</If>

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

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| params | An object containing the filter parameters as key value pairs as specified below | <If lang="javascript,nodejs,ruby,python,objc,swift">`Object`</If><If lang="java">[`Param[]`](#param)</If> |

##### `params` properties

| Property | Description | Type |
|----------|------|-------------|
| <If lang="javascript,nodejs,java,python,objc,swift">channel</If><If lang="ruby">:channel</If> | Filter to restrict to subscriptions associated with that `channel` | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">:client_id</If> | Optional filter to restrict to devices associated with that client identifier. Cannot be used with <If lang="javascript,nodejs,java,python,objc,swift">`deviceId`</If><If lang="ruby">`:device_id`</If> param | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">:device_id</If> | Optional filter to restrict to devices associated with that device identifier. Cannot be used with <If lang="javascript,nodejs,java,python,objc,swift">`clientId`</If><If lang="ruby">`:client_id`</If> param | `String` |

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="swift,objc">

##### Callback result

The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

When this operation fails, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>

## Related types 

### <If lang="javascript,nodejs,java,objc,swift,python">DeviceDetails</If><If lang="ruby">Ably::Models::DeviceDetails</If> 

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

#### Properties

| Property | Description | Type |
|----------|------|-------------|
| id | Unique identifier for the device generated by the device itself | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Optional trusted [client identifier](https://ably.com/docs/auth/identified-clients.md) for the device | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">formFactor</If><If lang="ruby">form_factor</If> | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` <If lang="java,ruby,python,objc,swift">or `embedded`</If><If lang="javascript,nodejs">`embedded` or `other`</If> | `String` |
| metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | <If lang="javascript,nodejs,java,python,objc,swift">`Object`</If><If lang="ruby">`Hash`</If> |
| platform | Platform of the push device. Must be one of `ios` <If lang="java,ruby,python,objc,swift">or `android`</If><If lang="javascript,nodejs">`android` or `browser`</If> | `String` |
| deviceSecret | Secret value for the device | `String` |
| push.recipient | Push recipient details for this device. See the [REST API push publish documentation](https://ably.com/docs/api/rest-api.md#message-extras-push) for more details | <If lang="javascript,nodejs,java,python,objc,swift">`Object`</If><If lang="ruby">`Hash`</If> |
| push.state | The current state of the push device being either <If lang="java,ruby,python,objc,swift">`Active`, `Failing` or `Failed`</If><If lang="javascript,nodejs">`ACTIVE`, `FAILING` or `FAILED`</If> | `String` |
| <If lang="java,python,objc,swift">push.errorReason</If><If lang="javascript,nodejs">push.error</If><If lang="ruby">push.error_reason</If> | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) |

### <If lang="javascript,nodejs,java,objc,swift,python">PushChannel</If><If lang="ruby">Ably::Models::PushChannel</If> 

A `PushChannel` is a property of a [`RealtimeChannel`](https://ably.com/docs/api/realtime-sdk/channels.md#properties) or [`RestChannel`](https://ably.com/docs/api/rest-sdk/channels.md#properties). It provides [push devices](https://ably.com/docs/push.md) the ability to subscribe and unsubscribe to push notifications on channels.

#### Methods

##### subscribeDevice 

<If lang="javascript,nodejs">

`subscribeDevice(): Promise<void>`

</If>
<If lang="ruby,python,java,objc,swift">

`subscribeDevice()`

</If>

Subscribe your device to the channel's push notifications.

<If lang="javascript,nodejs">

###### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### subscribeClient 

<If lang="javascript,nodejs">

`subscribeClient(): Promise<void>`

</If>
<If lang="ruby,python,java,objc,swift">

`subscribeClient()`

</If>

[Subscribe all devices associated with your device's clientId](https://ably.com/docs/push/publish.md#sub-channels) to the channel's push notifications.

<If lang="javascript,nodejs">

###### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### unsubscribeDevice 

<If lang="javascript,nodejs">

`unsubscribeDevice(): Promise<void>`

</If>

<If lang="ruby,python,java,objc,swift">

`unsubscribeDevice()`

</If>

Unsubscribe your device from the channel's push notifications.

<If lang="javascript,nodejs">

###### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### unsubscribeClient 

<If lang="javascript,nodejs">

`unsubscribeClient(): Promise<void>`

</If>
<If lang="ruby,python,java,objc,swift">

`unsubscribeClient()`

</If>

[Unsubscribe all devices associated with your device's clientId](https://ably.com/docs/push/publish.md#sub-channels) from the channel's push notifications.

<If lang="javascript,nodejs">

###### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### listSubscriptions 

<If lang="javascript,nodejs">

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

</If>
<If lang="java">

`PaginatedResult<PushChannelSubscription> listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)`

</If>
<If lang="objc,swift">

`listSubscriptions(deviceId: String?, clientId: String?, deviceClientId: String?, channel: String?, callback: (ARTPaginatedResult<PushChannelSubscription>?, ARTErrorInfo?) -> Void)`

</If>

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](push#push-admin). For more information, see `GET main.realtime.ably.net/push/channelSubscriptions` [Rest API](https://ably.com/docs/api/rest-api.md).

<If lang="javascript,nodejs">

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `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,000 | `Record<string, string>` |

</If>

<If lang="objc,swift">

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `String` |
| <If lang="objc,swift">callback</If> | <If lang="objc,swift">Called with a [`ARTPaginatedResult`](#paginated-result) object containing [`PushChannelSubscription`](https://ably.com/docs/api/realtime-sdk/push-admin.md#push-channel-subscription) objects or an error</If> | <If lang="objc,swift">Callback</If> |

</If>

<If lang="java">

##### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `String` |

</If>

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with [`PaginatedResult`](#paginated-result) which encapsulates an array of [PushChannelSubscription](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="objc,swift">

##### Callback result

On success, `resultPage` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [PushChannelSubscription](https://ably.com/docs/api/realtime-sdk/push-admin.md#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods.

On failure to retrieve message history, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="java">

##### Returns

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [PushChannelSubscription](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

Failure to retrieve the message history will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types.md#ably-exception)

</If>

### <If lang="javascript,nodejs,python">PushChannelSubscription</If><If lang="objc,swift">ARTPushChannelSubscription</If><If lang="java">ChannelSubscription</If><If lang="ruby">Art::Models::PushChannelSubscription</If> 

An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md) to a channel in order to receive push notifications.

#### <If lang="javascript,nodejs,python,objc,swift">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|------|-------------|
| channel | The channel that this push notification subscription is associated with | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">device_id</If> | The device with this identifier is linked to this channel subscription. When present, <If lang="javascript,nodejs,java,python,objc,swift">`clientId`</If><If lang="ruby">`client_id`</If> is never present | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](https://ably.com/docs/auth/identified-clients.md) are included in this channel subscription. When present, <If lang="javascript,nodejs,java,python,objc,swift">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | `String` |

<If lang="java,python,objc,swift,ruby">

### PushChannelSubscription constructors

#### <If lang="javascript,nodejs,java,python,objc,swift">PushChannelSubscription.forDevice</If><If lang="ruby">PushChannelSubscription.for_client</If> 

<If lang="javascript,nodejs,java,python,objc,swift">

`PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription`

</If>
<If lang="ruby">

`PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription`

</If>

A static factory method to create a `PushChannelSubscription` object for a channel and single device.

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| channel | Channel name linked to this push channel subscription | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">device_id</If> | The device with this identifier will be linked with this push channel subscription | `String` |

##### Returns

A [`PushChannelSubscription`](https://ably.com/docs/api/realtime-sdk/types.md#push-channel-subscription)  object

#### <If lang="javascript,nodejs,java,python,objc,swift">PushChannelSubscription.forClient</If><If lang="ruby">PushChannelSubscription.for_client</If> 

<If lang="javascript,nodejs,java,python,objc,swift">

`PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription`

</If>
<If lang="ruby">

`PushChannelSubscription.for_client(String channel, String client_id) -> PushChannelSubscription`

</If>

A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md).

##### Parameters

| Parameter | Description | Type |
|-----------|------|-------------|
| channel | Channel name linked to this push channel subscription | `String` |
| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](https://ably.com/docs/auth/identified-clients.md) are included in the new push channel subscription | `String` |

##### Returns

A `PushChannelSubscription` object

</If>

### <If lang="javascript,nodejs,python">PaginatedResult</If><If lang="swift,objc">ARTPaginatedResult</If><If lang="java">io.ably.lib.types.PaginatedResult</If><If lang="ruby">Ably::Models::PaginatedResult</If> 

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](https://ably.com/docs/api/rest-api.md#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object.

#### <If lang="javascript,nodejs,swift,objc,python">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|------|-------------|
| items | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | <If lang="javascript,nodejs,java,ruby,objc,swift">`Array <Message, Presence, Stats>`</If><If lang="python">`List <Message, Presence, Stats>`</If> |

#### Methods

##### first 

<If lang="javascript,nodejs">

`first(): Promise<PaginatedResult>`

</If>
<If lang="ruby">

`PaginatedResult first`

</If>
<If lang="python">

`PaginatedResult first()`

</If>
<If lang="java">

`PaginatedResult first()`

</If>
<If lang="objc,swift">

`first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>

<If lang="java,ruby,objc,swift,python">

Returns a new `PaginatedResult` for the first page of results. <If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and yields a [PaginatedResult](#paginated-result).</If>

</If>
<If lang="javascript,nodejs">

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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### hasNext 

<If lang="javascript,nodejs,java,objc,swift">

`Boolean hasNext()`

</If>
<If lang="ruby">

`Boolean has_next?`

</If>
<If lang="python">

`Boolean has_next()`

</If>

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

##### isLast 

<If lang="javascript,nodejs,java,objc,swift">

`Boolean isLast()`

</If>
<If lang="ruby">

`Boolean last?`

</If>
<If lang="python">

`Boolean is_last()`

</If>

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

##### next 

<If lang="javascript,nodejs">

`next(): Promise<PaginatedResult | null>`

</If>
<If lang="ruby">

`PaginatedResult next`

</If>
<If lang="python">

`PaginatedResult next()`

</If>
<If lang="java">

`PaginatedResult next()`

</If>
<If lang="objc,swift">

`next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>
<If lang="java,ruby,objc,swift,python">

Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then <If lang="javascript,nodejs,ruby">`null`</If><If lang="java">`Null`</If><If lang="python">`None`</If><If lang="objc,swift">`nil`</If> is returned. <If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and yields a [PaginatedResult](#paginated-result).</If>

</If>
<If lang="javascript,nodejs">

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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

##### current 

<If lang="javascript,nodejs,java,ruby,python,objc,swift">

`current(): Promise<PaginatedResult>`

</If>

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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### Example 

<If lang="javascript">

<Code>
```javascript
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());
```
</Code>

</If>
<If lang="nodejs">

<Code>
```nodejs
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());
```
</Code>

</If>

<If lang="java">

<Code>
```java
PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};
```
</Code>

</If>
<If lang="ruby">

<Code>
```ruby
# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end
```
</Code>

</If>

<If lang="python">

<Code>
```python
result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())
```
</Code>

</If>
<If lang="objc">

<Code>
```objc
[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast());
    }];
}];
```
</Code>

</If>
<If lang="swift">

<Code>
```swift
channel.history { paginatedResult, error in
    guard let paginatedResult = paginatedResult else {
        print("No results available")
        return
    }
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        guard let nextPage = nextPage else {
            print("No next page available")
            return
        }
        print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}
```
</Code>

</If>