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:

• 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

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

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.

JavaScriptNode.jsJavaAndroidC# .NETRubyPythonPHPObjective-CSwiftGo
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());
  });
});

Copy
Copied!