# Channels

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

<Code>

#### Javascript

```
const channels = realtime.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, RealtimeChannel>` |

</Table>

## Get a channel 

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

Creates a new [`RealtimeChannel`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-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 = realtime.channels.get('your-channel-name');

// With channel options
const encryptedChannel = realtime.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 or channel parameters. | <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. Supported params include [`rewind`](https://ably.com/docs/channels/options/rewind.md), [`delta`](https://ably.com/docs/channels/options/deltas.md), [`occupancy`](https://ably.com/docs/presence-occupancy/occupancy.md), and [`echo`](https://ably.com/docs/channels/options/echo.md). | `Record<String, String>` |
| modes | Optional | An array of channel mode values that restrict the operations a client can perform on a channel. | Array of <Table id='ChannelMode'/> |
| attachOnSubscribe | Optional | Whether calling [`subscribe()`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel.md#subscribe) on a channel or presence object should trigger an implicit attach. Default: `true`. | Boolean |

</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/realtime/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 

`RealtimeChannel`

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

## Get a derived channel 

`channels.getDerived(name: string, deriveOptions: DeriveOptions, channelOptions?: ChannelOptions): RealtimeChannel`

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

Derived channels enable you to subscribe to a filtered subset of messages on a channel using [subscription filters](https://ably.com/docs/channels.md#subscription-filters).

<Aside data-type='experimental'>
`getDerived()` is a preview feature and may change in a future non-major release.
</Aside>

<Code>

### Javascript

```
const derived = realtime.channels.getDerived('your-channel-name', {
  filter: "name == 'important'"
});
```
</Code>

### Parameters 

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

<Table id='GetDerivedParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| name | Required | The name of the channel. | String |
| deriveOptions | Required | The derive options used to filter the channel. | <Table id='DeriveOptions'/> |
| channelOptions | Optional | Options for the channel. | <Table id='ChannelOptions'/> |

</Table>

<Table id='DeriveOptions' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| filter | Optional | The [JMESPath](https://jmespath.org/) query filter string used to derive the new channel. | String |

</Table>

### Returns 

`RealtimeChannel`

Returns a derived [`RealtimeChannel`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel.md) object configured with the supplied filter.

## Release a channel 

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

Releases all SDK-held references to a [`RealtimeChannel`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-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.

Channels not already in the `initialized`, `detached`, or `failed` [state](https://ably.com/docs/channels/states.md) are detached before release. After release, calling [`channels.get()`](#get) with the same name returns a fresh channel object in the `initialized` state.

<Code>

### Javascript

```
realtime.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

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