Types

The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments.

Where client libraries support both Realtime and REST APIs, the types are shared between both clients.

All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object.

If you are interested in finding out more about the exact types and options definitions in each language, we recommend you download our open source libraries and review the code.

Data types

ChannelDetails

ChannelDetails is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.

The following is an example of a ChannelDetails JSON object:

  {
    "channelId": "foo",
    "status": {
      "isActive": true,
      "occupancy": {
        "metrics": {
          "connections": 1,
          "publishers": 1,
          "subscribers": 1,
          "presenceConnections": 1,
          "presenceMembers": 0,
          "presenceSubscribers": 1,
          "objectPublishers": 1,
          "objectSubscribers": 1
        }
      }
    }
  }

ChannelDetails.ChannelStatus

ChannelStatus is contained within the ChannelDetails object, and optionally contains an Occupancy object.

ChannelDetails.ChannelStatus.Occupancy

Occupancy is optionally contained within the ChannelStatus object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy attribute of the ChannelStatus object.

The occupancy attribute contains the metrics attribute, which contains the following members:

ErrorInfo

An ErrorInfo is a type encapsulating error information containing an Ably-specific error code and generic status code.

Properties

Error nesting

ErrorInfo objects can contain nested errors through the cause property, allowing you to trace the root cause of failures. When an operation fails due to underlying system errors, the main ErrorInfo provides the high-level failure reason while the nested cause contains more specific details about what went wrong.

One example of ErrorInfo nesting is 80019: Auth server rejecting request where the main error indicates token renewal failed, while the nested cause contains the specific HTTP error from the auth server.

The following example demonstrates how to handle nested errors:

function handleError(error) {
    console.log(`Main error: ${error.code} - ${error.message}`);

    // Check for nested error
    if (error.cause) {
        console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`);

        // Handle further nesting if needed
        if (error.cause.cause) {
            console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`);
        }
    }
}

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

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

Returns

An Array of Message objects

Message action

Message action is a String representing the action type of the message.

  const MessageActions = [
      'message.create',
      'message.update',
      'message.delete',
      'meta',
      'message.summary'
  ]

MessageAnnotations

Properties

PresenceMessage

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

Properties

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

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

Returns

An Array of PresenceMessage objects

Presence action

Presence action is a String with a value matching any of the Realtime Presence states & events.

  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

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":#paginated-result>

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

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());

HttpPaginatedResponse

An HttpPaginatedResponse is a superset of PaginatedResult, which is a type that represents a page of results plus metadata indicating the relative queries available to it. HttpPaginatedResponse additionally carries information about the response to an HTTP request. It is used when making custom HTTP requests.

Properties

Methods

first

first(): Promise<HttpPaginatedResponse>

Returns a promise. On success, the promise is fulfilled with a new HttpPaginatedResponse 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<HttpPaginatedResponse>

Returns a promise. On success, the promise is fulfilled with a new HttpPaginatedResponse 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<HttpPaginatedResponse>

Returns a promise. On success, the promise is fulfilled with a new HttpPaginatedResponse 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

The HttpPaginatedResponse interface is a superset of PaginatedResult, see the PaginatedResult example

PushChannelSubscription

An PushChannelSubscription is a type encapsulating the subscription of a device or group of devices sharing a client identifier to a channel in order to receive push notifications.

Properties

TokenDetails

TokenDetails is a type providing details of Ably Token string and its associated metadata.

Properties

TokenDetails constructors

TokenDetails.fromJson

TokenDetails.fromJson(String json) -> TokenDetails

A static factory method to create a TokenDetails from a deserialized TokenDetails-like object or a JSON stringified TokenDetails. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenDetails object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to the Ably standard which is milliseconds. By using the fromJson method when constructing a TokenDetails, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenDetails object

TokenRequest

TokenRequest is a type containing parameters for an Ably TokenRequest. Ably Tokens are requested using Auth#requestToken

Properties

TokenRequest constructors

TokenRequest.fromJson

TokenRequest.fromJson(String json) -> TokenRequest

A static factory method to create a TokenRequest from a deserialized TokenRequest-like object or a JSON stringified TokenRequest. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to the Ably standard which is milliseconds. By using the fromJson method when constructing a TokenRequest, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenRequest object

Stats object

A Stats object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.

Properties

StatsIntervalGranularity

StatsIntervalGranularity is an enum specifying the granularity of a Stats interval.

const StatsIntervalGranularity = [
    'minute',
    'hour',
    'day',
    'month'
]

BatchPublishSpec

A BatchPublishSpec describes the messages that should be published by a batch publish operation, and the channels to which they should be published.

Properties

BatchResult

A BatchResult contains information about the results of a batch operation.

Properties

BatchPublishSuccessResult

A BatchPublishSuccessResult contains information about the result of successful publishes to a channel requested by a single BatchPublishSpec.

Properties

BatchPublishFailureResult

A BatchPublishFailureResult contains information about the result of unsuccessful publishes to a channel requested by a single BatchPublishSpec.

Properties

BatchPresenceSuccessResult

A BatchPresenceSuccessResult contains information about the result of a successful batch presence request for a single channel.

Properties

BatchPresenceFailureResult

A BatchPresenceFailureResult contains information about the result of an unsuccessful batch presence request for a single channel.

Properties

TokenRevocationSuccessResult

A TokenRevocationSuccessResult contains information about the result of a successful token revocation request for a single target specifier.

Properties

TokenRevocationFailureResult

A TokenRevocationFailureResult contains information about the result of an unsuccessful token revocation request for a single target specifier.

Properties

Other types

AuthOptions Object

AuthOptions is a plain JavaScript object and is used when making authentication requests. If passed in, an authOptions object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported:

Properties

ClientOptions Object

ClientOptions is a plain JavaScript object and is used in the Ably.Realtime constructor's options argument. The following attributes can be defined on the object:

Properties

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

ChannelState

ChannelState is a String with a value matching any of the Realtime Channel states.

var ChannelStates = [
  'initialized',
  'attaching',
  'attached',
  'detaching',
  'detached',
  'failed',
  'suspended'
]

ChannelEvent

ChannelEvent is a String that can be emitted as an event on the Channel object; either a ChannelState or an update event.

var ChannelEvents = [
  'initialized',
  'attaching',
  'attached',
  'detaching',
  'detached',
  'failed',
  'suspended',
  'update'
]

ChannelStateChange Object

A ChannelStateChange is a type encapsulating state change information emitted by the Channel object. See Channel#on to register a listener for one or more events.

Properties

CipherParams

A CipherParams contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128.

Individual client libraries may support either instancing a CipherParams directly, using Crypto.getDefaultParams(), or generating one automatically when initializing a channel, as in this example.

Properties

ConnectionState

ConnectionState is a String with a value matching any of the Realtime Connection states.

var ConnectionStates = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed'
]

ConnectionEvent

ConnectionEvent is a String that can be emitted as an event on the Connection object; either a Realtime Connection state or an update event.

var ConnectionEvents = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed',
  'update'
]

ConnectionStateChange Object

A ConnectionStateChange is a type encapsulating state change information emitted by the Connection object. See Connection#on to register a listener for one or more events.

Properties

LastConnectionDetails

A LastConnectionDetails object provides details on the last connection in a browser environment persisted when the window beforeunload fired. This object is provided to the callback specified in the recover attribute of ClientOptions. The callback in turn instructs the client library whether the connection should be recovered or not. See connection state recovery for more information.

Please note that as sessionStorage is used to persist the LastConnectionDetails between page reloads, it is only available for pages in the same origin and top-level browsing context.

Properties

TokenParams Object

TokenParams is a plain JavaScript object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following attributes can be defined on the object:

Properties

TokenRevocationTargetSpecifier

TokenRevocationTargetSpecifier

A TokenRevocationTargetSpecifier describes which tokens should be affected by a token revocation request.

Properties

TokenRevocationOptions

TokenRevocationOptions

A TokenRevocationOptions describes the additional options accepted by revoke tokens request.

Properties