# Channel

A `Channel` represents a single channel, obtained via the [`channels.get()`](https://ably.com/docs/pub-sub/api/javascript/rest/channels.md#get) method. Use it to publish messages, retrieve message history, query the presence set, and access channel features such as push notifications and annotations.

The REST channel is stateless: each operation is a single HTTP request to Ably. Attaching, subscribing, and managing channel state require the [realtime SDK's `RealtimeChannel`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel.md) interface.

<Code>

#### Javascript

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

## Properties

The `Channel` interface has the following properties:

<Table id='ChannelProperties'>

| Property | Description | Type |
| --- | --- | --- |
| name | The name of this channel. | String |
| presence | Access the [`Presence`](https://ably.com/docs/pub-sub/api/javascript/rest/presence.md) object for this channel, used to query the presence set and its history. | [Presence](https://ably.com/docs/pub-sub/api/javascript/rest/presence.md) |
| push | Access the [`PushChannel`](https://ably.com/docs/pub-sub/api/javascript/rest/push-channel.md) object for this channel, used to manage push notification subscriptions. | [PushChannel](https://ably.com/docs/pub-sub/api/javascript/rest/push-channel.md) |
| annotations | Access the [`RestAnnotations`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-annotations.md) object for this channel, used to publish, delete, and retrieve [annotations](https://ably.com/docs/messages/annotations.md) on messages. | [RestAnnotations](https://ably.com/docs/pub-sub/api/javascript/rest/rest-annotations.md) |

</Table>

## Publish a message 

`channel.publish(name: string, data: any, options?: PublishOptions): Promise<PublishResult>`

Publish a single message on the channel based on a given event name and payload.

`channel.publish(message: Message, options?: PublishOptions): Promise<PublishResult>`

Publish a single message object on the channel.

`channel.publish(messages: Message[], options?: PublishOptions): Promise<PublishResult>`

Publish multiple messages atomically on the channel. This means that:

* Either all messages will be successfully published or none of them will.
* The [max message size](https://ably.com/docs/platform/pricing/limits.md#message) limit applies to the total size of all messages in the array.
* The publish counts as a single message for the purpose of [per-channel rate limit](https://ably.com/docs/platform/pricing/limits.md#message).
* If you are using client-specified message IDs, they must conform to certain restrictions.

Each call results in a single REST request to Ably. It is also possible to publish to multiple channels at once using the [batch publish](https://ably.com/docs/messages/batch.md#batch-publish) feature.

<Code>

### Javascript

```
await channel.publish('greeting', 'Hello, World!');

// Or with a Message object
await channel.publish({ name: 'greeting', data: 'Hello' });

// Or atomic batch
await channel.publish([
  { name: 'event1', data: 'one' },
  { name: 'event2', data: 'two' }
]);
```
</Code>

### Parameters 

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

<Table id='PublishParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| name | Required | The event name. | String |
| data | Required | The data payload for the message. Supported payload types are strings, JSON-serializable objects and arrays, buffers containing arbitrary binary data, and `null`. If sending binary data, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded. | Any |
| message | Required | A single [`Message`](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) object to publish. | [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |
| messages | Required | An array of [`Message`](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) objects to publish atomically. | [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md)[] |
| options | Optional | An open map of server-defined publish options (string, number, or boolean values), such as `quickAck`. The SDK passes these through as publish parameters; the set of valid options is defined by the Ably service, not the SDK. | <Table id='PublishOptions'/> |

</Table>

<Table id='PublishOptions' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| quickAck | Optional | Reduces the latency of REST publishes, though provides a slightly lower quality of service. | Boolean |

</Table>

### Returns 

`Promise<PublishResult>`

Returns a promise. The promise is fulfilled with a `PublishResult` when the message(s) have been delivered to Ably, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#errorinfo) object.

<Table id='PublishResult'>

| Property | Description | Type |
| --- | --- | --- |
| serials | An array of message serials corresponding 1:1 to the messages that were published. A serial may be `null` if the message was discarded due to a [message conflation](https://ably.com/docs/messages.md#conflation). | Array of String or Null |

</Table>

## Get message history 

`channel.history(params?: RestHistoryParams): Promise<PaginatedResult<InboundMessage>>`

Retrieve a [`PaginatedResult`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#PaginatedResult) of historical messages for this channel. If the channel is [configured to persist messages](https://ably.com/docs/storage-history/storage.md), message history is available for the duration configured for your account. If not, messages are only retained in memory by the Ably service for two minutes.

<Code>

### Javascript

```
const page = await channel.history({ limit: 50, direction: 'backwards' });
page.items.forEach((message) => console.log(message.data));
```
</Code>

### Parameters 

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

<Table id='HistoryParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Optional | Query parameters to filter and control retrieval, as specified in the [message history API documentation](https://ably.com/docs/storage-history/history.md#retrieve-channel). | <Table id='RestHistoryParams'/> |

</Table>

<Table id='RestHistoryParams' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| start | Optional | The time from which messages are retrieved, as milliseconds since the Unix epoch. Default: the beginning of time. | Number |
| end | Optional | The time until which messages are retrieved, as milliseconds since the Unix epoch. Default: current time. | Number |
| direction | Optional | The order of returned messages. `'backwards'` orders from most recent to oldest; `'forwards'` orders from oldest to most recent. Default: `'backwards'`. | String |
| limit | Optional | An upper limit on the number of messages returned. Default: 100. Maximum: 1000. | Number |

</Table>

### Returns 

`Promise<PaginatedResult<InboundMessage>>`

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 received [`Message`](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) objects (typed `InboundMessage`), or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#errorinfo) object.

## Get channel status 

`channel.status(): Promise<ChannelDetails>`

Retrieve the current status of the channel, including whether it is active and its [occupancy](https://ably.com/docs/presence-occupancy/occupancy.md) metrics, as a [`ChannelDetails`](https://ably.com/docs/pub-sub/api/javascript/rest/channel-details.md) object. This is the canonical, typed way to fetch a channel's current metadata on demand.

<Code>

### Javascript

```
const details = await channel.status();
console.log(details.status.occupancy.metrics.connections);
```
</Code>

### Returns 

`Promise<ChannelDetails>`

Returns a promise. The promise is fulfilled with a [`ChannelDetails`](https://ably.com/docs/pub-sub/api/javascript/rest/channel-details.md#ChannelDetails) object describing the channel's current state, or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md#errorinfo) object.

## Get a single message by serial 

`channel.getMessage(serialOrMessage: string | Message): Promise<Message>`

Retrieve the [latest version](https://ably.com/docs/messages/updates-deletes.md#get) of a message by its serial. Requires the `history` [capability](https://ably.com/docs/auth/capabilities.md).

### Parameters 

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

<Table id='GetMessageParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| serialOrMessage | Required | Either the serial identifier string of the message to retrieve, or a [`Message`](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) object containing a populated `serial` field. | String or [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |

</Table>

### Returns 

`Promise<Message>`

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

## Get all versions of a message 

`channel.getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`

Retrieve all historical [versions](https://ably.com/docs/messages/updates-deletes.md#versions) of a message identified by its serial, ordered by version. This includes the original message and all subsequent updates and delete operations. Requires the `history` [capability](https://ably.com/docs/auth/capabilities.md).

### Parameters 

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

<Table id='GetMessageVersionsParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| serialOrMessage | Required | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) object containing a populated `serial` field. | String or [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |
| params | Optional | Query parameters sent as part of the request, such as `limit`. | Object |

</Table>

### Returns 

`Promise<PaginatedResult<Message>>`

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

## Update a message 

`channel.updateMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>`

Publish an [update](https://ably.com/docs/messages/updates-deletes.md#update) to an existing message using shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message replace the corresponding fields in the existing message; null fields are left unchanged. Requires the `message-update-own` or `message-update-any` [capability](https://ably.com/docs/auth/capabilities.md).

### Parameters 

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

<Table id='UpdateMessageParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| message | Required | The message to update. Must include the `serial` of the message being updated. | [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |
| operation | Optional | Metadata about the update operation. | <Table id='MessageOperation'/> |
| options | Optional | Server-defined options affecting the publish of the update. | <Table id='PublishOptions'/> |

</Table>

<Table id='MessageOperation' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| clientId | Optional | The client ID performing the operation. | String |
| description | Optional | A human-readable description of why the operation was performed. | String |
| metadata | Optional | Additional metadata associated with the operation. | `Record<String, String>` |

</Table>

### Returns 

`Promise<UpdateDeleteResult>`

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

<Table id='UpdateDeleteResult'>

| Property | Description | Type |
| --- | --- | --- |
| versionSerial | The serial of the new version of the message produced by the update, delete, or append operation. `null` if the message was superseded by a subsequent update before it could be published. | String or Null |

</Table>

## Append to a message 

`channel.appendMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>`

[Append](https://ably.com/docs/messages/updates-deletes.md#append) data to an existing message on the channel. The supplied `data` is appended to the previous message's data, while `name` and `extras` replace the previous values if provided. Requires the `message-update-own` or `message-update-any` [capability](https://ably.com/docs/auth/capabilities.md).

For publishing a high rate of appends, you typically want to use a realtime client rather than a REST client, in order to preserve [append ordering](https://ably.com/docs/messages/updates-deletes.md#append-ordering).

### Parameters 

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

<Table id='AppendMessageParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| message | Required | The message to append data to. Must include the `serial` of the target message. | [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |
| operation | Optional | Metadata about the append operation. | <Table id='MessageOperation'/> |
| options | Optional | Server-defined options affecting the publish of the append. | <Table id='PublishOptions'/> |

</Table>

### Returns 

`Promise<UpdateDeleteResult>`

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

## Delete a message 

`channel.deleteMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>`

Mark a message as [deleted](https://ably.com/docs/messages/updates-deletes.md#delete) by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message replace the corresponding fields in the existing message; null fields are left unchanged. Requires the `message-delete-own` or `message-delete-any` [capability](https://ably.com/docs/auth/capabilities.md).

### Parameters 

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

<Table id='DeleteMessageParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| message | Required | The message to delete. Must include the `serial` of the message being deleted. | [Message](https://ably.com/docs/pub-sub/api/javascript/rest/message.md) |
| operation | Optional | Metadata about the delete operation. | <Table id='MessageOperation'/> |
| options | Optional | Server-defined options affecting the publish of the delete. | <Table id='PublishOptions'/> |

</Table>

### Returns 

`Promise<UpdateDeleteResult>`

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

## Related Topics

- [Channels](https://ably.com/docs/pub-sub/api/javascript/rest/channels.md): API reference for the Channels 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.