History
Channel object
The Realtime Channel object exposes the following public method to obtain Message history.
Methods
history
history(Object params?): Promise<PaginatedResult<Message>>
Gets a paginated set of historical messages for this channel.
Parameters
| Parameter | Description | Type |
|---|---|---|
| params | an optional object containing the query parameters | Object |
params parameters
| Property | Description | Type |
|---|---|---|
| start | Earliest time in milliseconds since the epoch for any messages retrieved. Default: beginning of time | Number |
| end | Latest time in milliseconds since the epoch for any messages retrieved. Default: current time | Number |
| direction | forwards or backwards. Default: backwards | String |
| limit | Maximum number of messages to retrieve up to 1,000. Default: 100 | Number |
| untilAttach | when true, ensures message history is up until the point of the channel being attached. See continuous history for more info. Requires the direction to be backwards (the default). If the Channel is not attached, or if direction is set to forwards, this option will result in an error. Default: false | Boolean |
Returns
Returns a promise. On success, the promise is fulfilled with a PaginatedResult encapsulating an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Presence object
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.
Methods
history
history(Object params?): Promise<PaginatedResult<PresenceMessage>>
Gets a paginated set of historical presence events for this channel.
Parameters
| Parameter | Description | Type |
|---|---|---|
| params | an optional object containing the query parameters, as specified below. | Object |
params parameters
| Property | Description | Type |
|---|---|---|
| start | Earliest time in milliseconds since the epoch for any presence events retrieved. Default: beginning of time | Number |
| end | Latest time in milliseconds since the epoch for any presence events retrieved. Default: current time | Number |
| direction | forwards or backwards. Default: backwards | String |
| limit | Maximum number of presence events to retrieve up to 1,000. Default: 100 | Number |
| untilAttach | when true, ensures presence message history is up until the point of the channel being attached. See continuous history for more info. Requires the direction to be backwards (the default). If the Channel is not attached, or if direction is set to forwards, this option will result in an error. Default: false | Boolean |
Returns
Returns a promise. On success, the promise is fulfilled with a PaginatedResult encapsulating an array of PresenceMessage objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods. 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.
Properties
| Property | Description | Type |
|---|---|---|
| name | The event name, if provided. | String |
| data | The message payload, if provided. | 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. | JSON Object |
| id | A Unique ID assigned by Ably to this message. | String |
| clientId | The client ID of the publisher of this message. | String |
| connectionId | The connection ID of the publisher of this message. | 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. | String |
| timestamp | Timestamp when the message was first received by the Ably, as milliseconds since the epoch. | 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. | String |
| action | The action type of the message, one of the MessageAction enum values. | 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. | String |
| annotations | An object containing information about annotations that have been made to the object. | 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
PresenceMessage
A PresenceMessage represents an individual presence update that is sent to or received from Ably.
Properties
| Property | Description | Type |
|---|---|---|
| action | the event signified by a PresenceMessage. See PresenceMessage.action | int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE } |
| data | The presence update payload, if provided | String, StringBuffer, JSON Object |
| extras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the push, ref and privileged objects. | JSON Object |
| id | Unique ID assigned by Ably to this presence update | String |
| clientId | The client ID of the publisher of this presence update | String |
| connectionId | The connection ID of the publisher of this presence update | String |
| timestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | 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 payload | String |
PresenceMessage constructors
PresenceMessage.fromEncoded
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
| Parameter | Description | Type |
|---|---|---|
| encodedPresMsg | a PresenceMessage-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 PresenceMessage object
PresenceMessage.fromEncodedArray
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
| Parameter | Description | Type |
|---|---|---|
| encodedPresMsgs | an array of PresenceMessage-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 PresenceMessage objects
Presence action
Presence action is a String with a value matching any of the Realtime Presence states & events.
1
2
3
4
5
6
7
var PresenceActions = [
'absent', // (reserved for internal use)
'present',
'enter',
'leave',
'update'
]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 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());