Channel
A Channel represents a single channel, obtained via the channels.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 interface.
1
const channel = rest.channels.get('all-gas-ion');Properties
The Channel interface has the following properties:
nameStringpushPushChannelPushChannel object for this channel, used to manage push notification subscriptions.annotationsRestAnnotationsRestAnnotations object for this channel, used to publish, delete, and retrieve annotations on messages.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 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.
- 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 feature.
1
2
3
4
5
6
7
8
9
10
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' }
]);Parameters
The publish() method takes the following parameters:
namerequiredStringdatarequiredAnynull. If sending binary data, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded.optionsoptionalPublishOptionsquickAck. The SDK passes these through as publish parameters; the set of valid options is defined by the Ably service, not the SDK.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 object.
serialsArray of String or Nullnull if the message was discarded due to a message conflation.Get message history
channel.history(params?: RestHistoryParams): Promise<PaginatedResult<InboundMessage>>Retrieve a PaginatedResult of historical messages for this channel. If the channel is configured to persist messages, 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.
1
2
const page = await channel.history({ limit: 50, direction: 'backwards' });
page.items.forEach((message) => console.log(message.data));Parameters
The history() method takes the following parameters:
paramsoptionalRestHistoryParamsReturns
Promise<PaginatedResult<InboundMessage>>
Returns a promise. The promise is fulfilled with a PaginatedResult containing an array of received Message objects (typed InboundMessage), or rejected with an ErrorInfo object.
Get channel status
channel.status(): Promise<ChannelDetails>Retrieve the current status of the channel, including whether it is active and its occupancy metrics, as a ChannelDetails object. This is the canonical, typed way to fetch a channel's current metadata on demand.
1
2
const details = await channel.status();
console.log(details.status.occupancy.metrics.connections);Returns
Promise<ChannelDetails>
Returns a promise. The promise is fulfilled with a ChannelDetails object describing the channel's current state, or rejected with an ErrorInfo object.
Get a single message by serial
channel.getMessage(serialOrMessage: string | Message): Promise<Message>Retrieve the latest version of a message by its serial. Requires the history capability.
Parameters
The getMessage() method takes the following parameters:
Returns
Promise<Message>
Returns a promise. The promise is fulfilled with the Message, or rejected with an ErrorInfo object.
Get all versions of a message
channel.getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>Retrieve all historical 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.
Parameters
The getMessageVersions() method takes the following parameters:
Returns
Promise<PaginatedResult<Message>>
Returns a promise. The promise is fulfilled with a PaginatedResult of message versions, or rejected with an ErrorInfo object.
Update a message
channel.updateMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>Publish an 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.
Parameters
The updateMessage() method takes the following parameters:
serial of the message being updated.operationoptionalMessageOperationoptionsoptionalPublishOptionsReturns
Promise<UpdateDeleteResult>
Returns a promise. The promise is fulfilled with an UpdateDeleteResult containing the updated version metadata, or rejected with an ErrorInfo object.
versionSerialString or Nullnull if the message was superseded by a subsequent update before it could be published.Append to a message
channel.appendMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>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.
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.
Parameters
The appendMessage() method takes the following parameters:
serial of the target message.operationoptionalMessageOperationoptionsoptionalPublishOptionsReturns
Promise<UpdateDeleteResult>
Returns a promise. The promise is fulfilled with an UpdateDeleteResult, or rejected with an ErrorInfo object.
Delete a message
channel.deleteMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>Mark a message as deleted 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.
Parameters
The deleteMessage() method takes the following parameters:
serial of the message being deleted.operationoptionalMessageOperationoptionsoptionalPublishOptionsReturns
Promise<UpdateDeleteResult>
Returns a promise. The promise is fulfilled with an UpdateDeleteResult, or rejected with an ErrorInfo object.