# Channels

The `Channels` interface is used to create and destroy [`Channel`](https://ably.com/docs/pub-sub/api/javascript/rest/channel.md) objects. Access it via the `channels` property of a [`Rest`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md) client instance.

<Code>

#### Javascript

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

## Properties

The `Channels` interface has the following properties:

<Table id='ChannelsProperties'>

| Property | Description | Type |
| --- | --- | --- |
| all | A map of all the channels that have been instantiated via [`get()`](#get) and have not yet been released via [`release()`](#release). | `Record<String, Channel>` |

</Table>

## Get a channel 

`channels.get(name: string, channelOptions?: ChannelOptions): Channel`

Creates a new [`Channel`](https://ably.com/docs/pub-sub/api/javascript/rest/channel.md) object if none for the given name exists, or returns the existing channel object. The channel is created or returned with the supplied `ChannelOptions`.

<Code>

### Javascript

```
const channel = rest.channels.get('your-channel-name');

// With channel options
const encryptedChannel = rest.channels.get('your-channel-name', {
  cipher: { key: '<key>' }
});
```
</Code>

### Parameters 

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

<Table id='GetParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| name | Required | The name of the channel. | String |
| channelOptions | Optional | Options for the channel, such as encryption. | <Table id='ChannelOptions'/> |

</Table>

<Table id='ChannelOptions' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| cipher | Optional | Requests [encryption](https://ably.com/docs/channels/options/encryption.md) for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length, and key). | <Table id='CipherParams'/> or <Table id='CipherParamOptions'/> |
| params | Optional | [Channel parameters](https://ably.com/docs/channels/options.md) that configure the behavior of the channel. | `Record<String, String>` |
| modes | Optional | An array of channel mode values that restrict the operations a client can perform on a channel. Modes are applied when a realtime connection attaches to the channel; they have no effect on REST operations, which are governed by [capabilities](https://ably.com/docs/auth/capabilities.md). | Array of <Table id='ChannelMode'/> |

</Table>

<Table id='CipherParams' >

| Property | Description | Type |
| --- | --- | --- |
| key | The private key used for encryption and decryption. Do not set this value directly; pass a key to [`Crypto.getDefaultParams()`](https://ably.com/docs/pub-sub/api/javascript/rest/crypto.md#get-default-params) instead. | `unknown` |
| algorithm | The name of the algorithm. Default: `AES`. | String |
| keyLength | The key length in bits of the cipher. Either 128 or 256. Default: 256. | Number |
| mode | The cipher mode. Default: `CBC`. | String |

</Table>

<Table id='CipherParamOptions' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| key | Required | The private key used for encryption and decryption. Can be binary or base64-encoded. | `ArrayBuffer`, `Uint8Array`, or String |
| algorithm | Optional | The name of the algorithm. Default: `AES`. | String |
| keyLength | Optional | The key length in bits. Either 128 or 256. Default: 256. | Number |
| mode | Optional | The cipher mode. Default: `CBC`. | String |

</Table>

<Table id='ChannelMode' >

| Value | Description |
| --- | --- |
| PUBLISH | The client can publish messages to the channel. |
| SUBSCRIBE | The client can subscribe to messages on the channel. |
| PRESENCE | The client can enter the presence set on the channel. |
| PRESENCE_SUBSCRIBE | The client can subscribe to presence events on the channel. |
| OBJECT_PUBLISH | The client can publish LiveObjects messages on the channel. |
| OBJECT_SUBSCRIBE | The client can subscribe to LiveObjects messages on the channel. |
| ANNOTATION_PUBLISH | The client can publish annotations on the channel. |
| ANNOTATION_SUBSCRIBE | The client can subscribe to annotations on the channel. |

</Table>

### Returns 

`Channel`

Returns a [`Channel`](https://ably.com/docs/pub-sub/api/javascript/rest/channel.md) object for the given name. If a channel with that name already exists, the existing object is returned.

## Release a channel 

`channels.release(name: string): void`

Releases all SDK-held references to a [`Channel`](https://ably.com/docs/pub-sub/api/javascript/rest/channel.md) object, enabling it to be garbage collected. Useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it.

<Aside data-type='important'>
This method has no guardrails: using a channel reference after `release()` has been called is undefined behaviour.
</Aside>

This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected. After release, calling [`channels.get()`](#get) with the same name returns a fresh channel object.

<Code>

### Javascript

```
rest.channels.release('your-channel-name');
```
</Code>

### Parameters 

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

<Table id='ReleaseParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| name | Required | The name of the channel to release. | String |

</Table>

## Related Topics

- [Channel](https://ably.com/docs/pub-sub/api/javascript/rest/channel.md): API reference for the Channel interface in the Ably Pub/Sub JavaScript REST SDK.
- [ChannelDetails](https://ably.com/docs/pub-sub/api/javascript/rest/channel-details.md): API reference for channel metadata (ChannelDetails) in the Ably Pub/Sub JavaScript REST SDK.
- [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md): API reference for the Message interface in the Ably Pub/Sub JavaScript REST SDK.
- [RestAnnotations](https://ably.com/docs/pub-sub/api/javascript/rest/rest-annotations.md): API reference for message annotations (the RestAnnotations 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.