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

Ably::Exceptions::BaseAblyException

A BaseAblyException is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable.

Attributes

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:

Ably::Models::DeviceDetails

A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.

Properties

Ably::Models::LocalDevice

An extension of DeviceDetails. In addition to the properties of DeviceDetails, it includes the following:

Properties

Ably::Models::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:

def handle_error(error)
  puts "Main error: #{error.code} - #{error.message}"

  if error.cause
    puts "Root cause: #{error.cause.code} - #{error.cause.message}"

    if error.cause.cause
      puts "Deeper cause: #{error.cause.cause.code} - #{error.cause.cause.message}"
    end
  end
end

Ably::Models::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, Binary (ASCII-8BIT String), Hash, Array

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: Hash, Array

id

A Unique ID assigned by Ably to this message.
Type: String

client_id

The client ID of the publisher of this message.
Type: String

connection_id

The connection ID of the publisher of this message.
Type: String

connectionKeyconnection_key

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 a Time object.

Type: Time

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

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

MessageAnnotations

Attributes

PublishResult

Contains the result of a publish operation.

Attributes

UpdateDeleteResult

Contains the result of an update, delete, or append message operation.

Attributes

Ably::Models::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

Ably::Models::PresenceMessage::ACTION

Ably::Models::PresenceMessage::ACTION is an enum-like value representing all the Realtime Presence states & events. ACTION can be represented interchangeably as either symbols or constants.

Symbol states

  :absent  # => 0 (reserved for internal use)
  :present # => 1
  :enter   # => 2
  :leave   # => 3
  :update  # => 4

Constant states

  PresenceMessage::ACTION.Absent  # => 0 (internal use)
  PresenceMessage::ACTION.Present # => 1
  PresenceMessage::ACTION.Enter   # => 2
  PresenceMessage::ACTION.Leave   # => 3
  PresenceMessage::ACTION.Update  # => 4

Example usage

  # Example with symbols
  presence.on(:attached) { ... }

  # Example with constants
  presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }

  # Interchangeable
  Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true

Ably::Models::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.

Attributes

Methods

first

PaginatedResult first

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

has_next?

Boolean has_next?

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

last?

Boolean last?

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

next

PaginatedResult next

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

Example

# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end

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.

Attributes

Methods

first

HttpPaginatedResponse first

Returns a new HttpPaginatedResponse for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields an HttpPaginatedResponse.

has_next?

Boolean has_next?

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

last?

Boolean last?

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

next

HttpPaginatedResponse next

Returns a new HttpPaginatedResponse loaded with the next page of results. If there are no further pages, then null is returned. When using the Realtime library, the first method returns a Deferrable and yields an HttpPaginatedResponse.

Example

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

Ably::Models::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

Ably::Models::TokenDetails

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

Attributes

Methods

TokenDetails constructors

TokenDetails.from_json

TokenDetails.from_json(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

Ably::Models::TokenRequest

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

Attributes

TokenRequest constructors

TokenRequest.fromJson

TokenRequest.from_json(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

Ably::Models::Stats

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.

Please note that most attributes of the Stats type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby uses under_score case instead of the default camelCase in most languages, so please bear that in mind.

Attributes

Other types

AuthOptions Hash

AuthOptions is a Hash object and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash:

Attributes

ClientOptions Hash

ClientOptions is a Hash object and is used in the Ably::Realtime constructor's options argument. The following key symbol values can be added to the Hash:

Attributes

ChannelOptions Hash

Channel options are used for configuring encryption.

ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:

Attributes

Channel::STATE Enum

Ably::Realtime::Channel::STATE is an enum-like value representing all the Realtime Channel states. STATE can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # => 0
:attaching # =>   1
:attached # =>    2
:detaching # =>   3
:detached # =>    4
:failed # =>      5

Constant states

Channel::STATE.Initialized # => 0
Channel::STATE.Attaching # =>   1
Channel::STATE.Attached # =>    2
Channel::STATE.Detaching # =>   3
Channel::STATE.Detached # =>    4
Channel::STATE.Failed # =>      5

Example usage

# Example with symbols
channel.on(:attached) { ... }

# Example with constants
channel.on(Ably::Realtime::Channel::STATE.Attached) { ... }

# Interchangeable
Ably::Realtime::Channel::STATE.Attached == :attached # => true

Channel::EVENT Enum

Ably::Realtime::Channel::EVENT is an enum-like value representing all the events that can be emitted be the Channel; either a ChannelState or an :update event. EVENT can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # => 0
:attaching # =>   1
:attached # =>    2
:detaching # =>   3
:detached # =>    4
:failed # =>      5
:update # =>      6

Constant states

Channel::EVENT.Initialized # => 0
Channel::EVENT.Attaching # =>   1
Channel::EVENT.Attached # =>    2
Channel::EVENT.Detaching # =>   3
Channel::EVENT.Detached # =>    4
Channel::EVENT.Failed # =>      5
Channel::EVENT.Update # =>      6

ChannelStateChange

A Ably::Models::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 Hash

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.get_default_params(), or generating one automatically when initializing a channel, as in this example.

Properties

Connection::STATE

Ably::Realtime::Connection::STATE is an enum-like value representing all the Realtime Connection states. STATE can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # =>  0
:connecting # =>   1
:connected # =>    2
:disconnected # => 3
:suspended # =>    4
:closing # =>      5
:closed # =>       6
:failed # =>       7

Constant states

Connection::STATE.Initialized # =>  0
Connection::STATE.Connecting # =>   1
Connection::STATE.Connected # =>    2
Connection::STATE.Disconnected # => 3
Connection::STATE.Suspended # =>    4
Connection::STATE.Closing # =>      5
Connection::STATE.Closed # =>       6
Connection::STATE.Failed # =>       7

Example usage

# Example with symbols
client.connection.on(:connected) { ... }

# Example with constants
client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... }

# Interchangeable
Ably::Realtime::Connection::STATE.Connected == :connected # => true

Connection::EVENT Enum

Ably::Realtime::Connection::EVENT is an enum-like value representing all the events that can be emitted be the Connection; either a Realtime Connection state or an :update event. EVENT can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # =>  0
:connecting # =>   1
:connected # =>    2
:disconnected # => 3
:suspended # =>    4
:closing # =>      5
:closed # =>       6
:failed # =>       7
:update # =>       8

Constant states

Connection::EVENT.Initialized # =>  0
Connection::EVENT.Connecting # =>   1
Connection::EVENT.Connected # =>    2
Connection::EVENT.Disconnected # => 3
Connection::EVENT.Suspended # =>    4
Connection::EVENT.Closing # =>      5
Connection::EVENT.Closed # =>       6
Connection::EVENT.Failed # =>       7
Connection::EVENT.Update # =>       8

Example usage

# Example with symbols
client.connection.on(:connected) { ... }

# Example with constants
client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... }

# Interchangeable
Ably::Realtime::Connection::STATE.Connected == :connected # => true

ConnectionStateChange

A Ably::Models::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.

Attributes

Ably::Util::SafeDeferrable

The SafeDeferrable class provides an EventMachine compatible Deferrable.

A SafeDeferrable ensures that any exceptions in callbacks provided by developers will not break the client library and stop further execution of code.

Methods

callback

callback(&block)

Specify a block to be executed if and when the Deferrable object receives a status of :succeeded. See the EventMachine callback documentation

errback

errback(&block)

Specify a block to be executed if and when the Deferrable object receives a status of :failed. See the EventMachine errback documentation

fail

fail(*args)

Mark the Deferrable as failed and trigger all callbacks. See the EventMachine fail documentation

succeed

succeed(*args)

Mark the Deferrable as succeeded and trigger all callbacks. See the EventMachine succeed documentation

TokenParams Hash

TokenParams is a Hash object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following key symbol values can be added to the Hash:

Attributes