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:

Channel get(String channelName, ChannelOptions channelOptions)

Creates a new Channel object if none for the channel exists, or returns the existing channel object.

release(String channelName)

Releases a Channel object, deleting it and enabling it to be garbage collected.

The Channel object, created via the Channels object, is used to interact with a specific channel.

The Channel object exposes the following public properties:

The name String unique to this channel.

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.

Provides access to the PushChannel object for this channel which can be used to access members present on the channel, or participate in presence.

There are two overloaded versions of this method:

publish(String name, Object data, callback(ErrorInfo err))

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(Object[] messages, callback(ErrorInfo err))

Publish several messages on this channel.

The entire messages array is published atomically. This means that:

Parameters

name
event name for the published messageType: String
messages
An array of message objects to publishType: Message []

history(Object options, callback(ErrorInfo err, PaginatedResult<Message> resultPage))

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

options
an optional object containing the query parameters, as specified in the message history API documentation.

A Message represents an individual message that is sent to or received from Ably.

Properties

name
Event name, if providedType: String
data
The presence update payload, if providedType:
extras
Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the push, ref and privileged objects.Type:
id
Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of idempotent publishingType: String
clientId
The client ID of the publisher of this messageType: String
connectionId
The connection ID of the publisher of this messageType: String
timestamp
Timestamp when the message was received by the Ably service, as milliseconds since the epochType: 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 payloadType: String

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

encodedMsg
a Message-like deserialized object.Type: Object
channelOptions
an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type: Object

Returns

A Message object

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

encodedMsgs
an array of Message-like deserialized objects.Type: Array
channelOptions
an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type: Object

Returns

An Array of Message objects

Channel options are used for configuring encryption.

Properties

Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an exampleType: CipherParams

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

items
contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request)Type: Array <Message, Presence, Stats>

Methods

first(callback(ErrorInfo err, PaginatedResult resultPage))

Returns a new PaginatedResult for the first page of results.

Boolean hasNext()

Returns true if there are more pages available by calling next and returns false if this page is the last page available.

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(callback(ErrorInfo err, PaginatedResult resultPage))

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned.

Select...
channel.history(function(err, paginatedResult) { console.log('Page 0 item 0:' + paginatedResult.items[0].data); paginatedResult.next(function(err, nextPage) { console.log('Page 1 item 1: ' + nextPage.items[1].data); console.log('Last page?: ' + nextPage.isLast()); }); });
Copied!
Channels
v2.0