# Push

The `Push` object provides device-level [push notification](https://ably.com/docs/push.md) management, such as activating and deactivating the local device. Access it via the `push` property of a [`Rest`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md) client instance (`rest.push`).

Device activation operates on the local device's push registration, so it is only meaningful in environments that have a push-capable device, such as a browser or a mobile app. For server-side push administration, use the [`PushAdmin`](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md) object instead.

<Code>

#### Javascript

```
const push = rest.push;
```
</Code>

## Properties

The `Push` interface has the following properties:

<Table id='PushProperties'>

| Property | Description | Type |
| --- | --- | --- |
| admin | A [`PushAdmin`](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md) object for managing push notifications administratively (requires the `push-admin` capability). | [PushAdmin](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md) |

</Table>

## Activate the device 

`push.activate(registerCallback?: Function, updateFailedCallback?: Function): Promise<void>`

[Activates the device](https://ably.com/docs/push/configure/web.md#browser) for push notifications. Subsequently registers the device with Ably and stores the `deviceIdentityToken` in local storage.

<Code>

### Javascript

```
await rest.push.activate();
```
</Code>

### Parameters 

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

<Table id='ActivateParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| registerCallback | Optional | A function passed to override the default implementation to register the local device for push activation. Called with the local device's [`DeviceDetails`](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md#DeviceDetails) and a callback of the form `callback(err, deviceDetails)`, where `err` is an `ErrorInfo` or `null` and `deviceDetails` is the registered `DeviceDetails`. | Function |
| updateFailedCallback | Optional | A callback to be invoked when the device registration fails to update. Called with an `ErrorInfo` or `null` as `updateFailedCallback(err)`. | Function |

</Table>

### Returns 

`Promise<void>`

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

## Deactivate the device 

`push.deactivate(deregisterCallback?: Function): Promise<void>`

Deactivates the device from receiving push notifications.

<Code>

### Javascript

```
await rest.push.deactivate();
```
</Code>

### Parameters 

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

<Table id='DeactivateParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| deregisterCallback | Optional | A function passed to override the default implementation to deregister the local device for push activation. Called with the local device's [`DeviceDetails`](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md#DeviceDetails) and a callback of the form `callback(err, deviceId)`, where `err` is an `ErrorInfo` or `null` and `deviceId` is the deregistered device's ID string. | Function |

</Table>

### Returns 

`Promise<void>`

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

## LocalDevice 

A `LocalDevice` represents the current device as registered for push notifications, exposing the identity token and secret it uses to authenticate itself with Ably. Access it by calling `await rest.getDevice()`.

### Properties

<Table id='LocalDevice'>

| Property | Description | Type |
| --- | --- | --- |
| id | A unique ID generated by the device. | String |
| deviceSecret | A unique device secret generated by the Ably SDK. | String |
| deviceIdentityToken | A unique identity token the device uses to authenticate itself with Ably. Not present until device activation has completed. | String or Undefined |

</Table>

### List subscriptions for the local device 

`localDevice.listSubscriptions(): Promise<PaginatedResult<PushChannelSubscription>>`

Retrieves push subscriptions active for the local device.

<Code>

#### Javascript

```
const device = await rest.getDevice();
const subs = await device.listSubscriptions();
```
</Code>

#### Returns 

`Promise<PaginatedResult<PushChannelSubscription>>`

Returns a promise. The promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#PaginatedResult) containing an array of `PushChannelSubscription` objects for each push channel subscription active for the local device, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#errorinfo) object.

<Table id='PushChannelSubscription'>

| Property | Description | Type |
| --- | --- | --- |
| channel | The channel that this push notification subscription is associated with. | String |
| deviceId | The device with this identifier is linked to this channel subscription. When present, `clientId` is never present. | String or Undefined |
| clientId | Devices with this [client identifier](https://ably.com/docs/auth/identified-clients.md) are included in this channel subscription. When present, `deviceId` is never present. | String or Undefined |

</Table>

## Related Topics

- [PushChannel](https://ably.com/docs/pub-sub/api/javascript/rest/push-channel.md): API reference for the PushChannel interface in the Ably Pub/Sub JavaScript REST SDK.
- [PushAdmin](https://ably.com/docs/pub-sub/api/javascript/rest/push-admin.md): API reference for the Push admin (PushAdmin) interface in the Ably Pub/Sub JavaScript REST 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.