API v 1.0
JavaScript

History

The Realtime Channel object exposes the following public method to obtain Message history.

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

Gets a paginated set of historical messages for this channel.

Parameters

option
an optional object containing the query parameters, as specified below.
callback
is a function of the form: function(err, resultPage)

options parameters

start
beginning of time earliest time in milliseconds since the epoch for any messages retrievedType: Long
end
current time latest time in milliseconds since the epoch for any messages retrievedType: Long
direction
backwards forwards or backwardsType: String
limit
100 maximum number of messages to retrieve up to 1,000Type: Integer
untilAttach
false when true, ensures message history is up until the point of the channel being attached. See continuous history for more info. If the Channel is not attached, enabling this option will result in errorType: Boolean

Realtime Presence object exposes the following public method to obtain presence event history such as enter, update and leave events. These events are represented as PresenceMessage objects.

history(Object option, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))

Gets a paginated set of historical presence events for this channel.

Parameters

option
an optional object containing the query parameters, as specified below.
callback
is a function of the form: function(err, resultPage)

options parameters

start
beginning of time earliest time in milliseconds since the epoch for any presence events retrievedType: Long
end
current time latest time in milliseconds since the epoch for any presence events retrievedType: Long
direction
backwards forwards or backwardsType: String
limit
100 maximum number of presence events to retrieve up to 1,000Type: Integer
untilAttach
false when true, ensures presence event history is up until the point of the channel being attached. See continuous history for more info. If the Channel is not attached, enabling this option will result in errorType: Boolean

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 payload for extras is the push object.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

A PresenceMessage represents an individual presence update that is sent to or received from Ably.

Properties

action
the event signified by a PresenceMessage. See Presence actionType: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }
data
The presence update payload, if provided
extras
Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the push object.Type:
id
Unique ID assigned by Ably to this presence updateType: String
clientId
The client ID of the publisher of this presence updateType: String
connectionId
The connection ID of the publisher of this presence updateType: String
timestamp
Timestamp when the presence update was received by Ably, as milliseconds since the epoch.Type: Integer
encoding
This will typically be empty as all presence updates 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

PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) → PresenceMessage

A static factory method to create a PresenceMessage from a deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsg
a PresenceMessage-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 PresenceMessage object

PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) → PresenceMessage[]

A static factory method to create an array of PresenceMessages from an array of deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsgs
an array of PresenceMessage-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 PresenceMessage objects

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.

JavaScript
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!