Channels
Channels
The Channels object, accessed from the rest library client constructor, is used to create and destroy Channel objects. It exposes the following public methods:
Channels Methods
get
Channel get(String channelName, ChannelOptions channelOptions)
Creates a new Channel object if none for the channel exists, or returns the existing channel object.
release
release(String channelName)
Releases a Channel object, deleting it from the local SDK client instance and enabling it to be garbage collected.
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 releasing a channel, calling channels.get(channelName) will create a fresh channel object. If using a singleton REST client pattern with multiple execution contexts, be cautious when calling release as it will affect all parts of your application using that client instance. Subsequent publish operations on the same channel name will require obtaining a new channel object.
Channel
The Channel object, created via the Channels object, is used to interact with a specific channel.
Channel Properties
The Channel object exposes the following public properties:
name
The name String unique to this channel.
presence
Provides access to the REST Presence object for this channel which can be used to get members present on the channel, or retrieve presence event history.
push
Provides access to the PushChannel object for this channel which can be used to access members present on the channel, or participate in presence.
Channel Methods
publish
There are two overloaded versions of this method:
publish(String name, Object data, PublishOptions options?) Promise<Void>
Publish a single message on this channel based on a given event name and payload.
It is also possible to publish a message to multiple channels at once using our batch publish feature.
publish(Message message, PublishOptions options?): Promise<void>
Publish a single message on this channel.
publish(Message[] messages, PublishOptions options?): Promise<Void>
Publish several messages on this channel.
The entire messages array is published atomically. This means that:
- Either they will all 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 will only count as a single message for the purpose of per-channel rate limit
- If you are using client-specified message IDs for publish idempotency, they must conform to certain restrictions
Parameters
| Parameter | Description | Type |
|---|---|---|
| data | Data payload for the message. The supported payload types are Strings, objects or arrays capable of JSON representation, buffers containing arbitrary binary data, and null. (Note that if sending a binary, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded) | Object |
| messages | An array of message objects to publish | Message [] |
| options | Optional parameters to provide to the publish operation | PublishOptions |
Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
history
history(Object params?): Promise<PaginatedResult<Message>>
Gets a paginated set of historical messages for this channel. If the channel is configured to persist messages to disk, then message history will typically be available for 24 - 72 hours. If not, messages are only retained in memory by the Ably service for two minutes.
Parameters
| Parameter | Description | Type |
|---|---|---|
| params | An optional object containing the query parameters, as specified in the message history API documentation | Object |
Returns
Returns a promise. On success, the promise is fulfilled with a PaginatedResult object containing an array of messages. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Related types
Message
A Message represents an individual message that is sent to or received from Ably.
name
The event name, if provided.
Type: String
data
The message payload, if provided.
Type: String, StringBuffer, JSON Object
extras
Metadata and/or ancillary payloads, if provided. Valid payloads include push, headers (a map of strings to strings for arbitrary customer-supplied metadata), ephemeral, and privileged objects.
Type: JSON Object
id
A Unique ID assigned by Ably to this message.
Type: String
clientId
The client ID of the publisher of this message.
Type: String
connectionId
The connection ID of the publisher of this message.
Type: String
connectionKey
A connection key, which can optionally be included for a REST publish as part of the publishing on behalf of a realtime client functionality.
Type: String
timestamp
Timestamp when the message was first received by the Ably, as milliseconds since the epoch.
Type: Integer
encoding
This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
Type: String
action
The action type of the message, one of the MessageAction enum values.
Type: int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }
serial
A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in channel rules .
Type: String
annotations
An object containing information about annotations that have been made to the object.
Type: MessageAnnotations
Message constructors
Message.fromEncoded
Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message
A static factory method to create a Message from a deserialized Message-like object encoded using Ably's wire protocol.
Parameters
| Parameter | Description | Type |
|---|---|---|
| encodedMsg | A Message-like deserialized object | Object |
| channelOptions | An optional ChannelOptions. If you have an encrypted channel, use this to allow the library to decrypt the data | Object |
Returns
A Message object
Message.fromEncodedArray
Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]
A static factory method to create an array of Messages from an array of deserialized Message-like object encoded using Ably's wire protocol.
Parameters
| Parameter | Description | Type |
|---|---|---|
| encodedMsgs | An array of Message-like deserialized objects | Array |
| channelOptions | An optional ChannelOptions. If you have an encrypted channel, use this to allow the library to decrypt the data | Object |
Returns
An Array of Message objects
ChannelOptions Object
Channel options are used for setting channel parameters and configuring encryption.
ChannelOptions, a plain JavaScript object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following attributes can be defined on the object:
Properties
| Parameter | Description | Type |
|---|---|---|
| params | Optional parameters which specify behaviour of the channel | JSON Object |
| cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example | CipherParams or an options object containing at a minimum a key |
PublishOptions
Options passed to a publish() operation to customize its behavior.
Parameters
| Parameter | Description | Type |
|---|---|---|
| quickAck | Reduces the latency of REST publishes, though provides a slightly lower quality of service | Boolean |
PaginatedResult
A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.
Properties
| Property | Description | Type |
|---|---|---|
| items | contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request) | Array <Message, Presence, Stats> |
Methods
first
first(): Promise<PaginatedResult>
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult for the first page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
hasNext
Boolean hasNext()
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
isLast
Boolean isLast()
Returns true if this page is the last page and returns false if there are more pages available by calling next available.
next
next(): Promise<PaginatedResult | null>
Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned.
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
current
current(): Promise<PaginatedResult>
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the current page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Example
1
2
3
4
5
const paginatedResult = await channel.history();
console.log('Page 0 item 0:' + paginatedResult.items[0].data);
const nextPage = await paginatedResult.next();
console.log('Page 1 item 1: ' + nextPage.items[1].data);
console.log('Last page?: ' + nextPage.isLast());