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.

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.

channelId
the required name of the channel including any qualifier, if anyType: string
region
in events relating to the activity of a channel in a specific region, this optionally identifies the regionType: string
isGlobalMaster
in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channelType: boolean
status
an optional ChannelStatus instanceType: ChannelStatus

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 } } } }
Copied!

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

isActive
a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activityType: boolean
occupancy
an optional Occupancy instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.Type: 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:

connections
the number of connectionsType: integer
publishers
the number of connections attached to the channel that are authorised to publishType: integer
subscribers
the number of connections attached that are authorised to subscribe to messagesType: integer
presenceSubscribers
the number of connections that are authorised to subscribe to presence messagesType: integer
presenceConnections
the number of connections that are authorised to enter members into the presence channelType: integer
presenceMembers
the number of members currently entered into the presence channelType: integer

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

Properties

code
Ably error code (see ably-common/protocol/errors.json)Type: Integer
statusCode
HTTP Status Code corresponding to this error, where applicableType: Integer
message
Additional message information, where availableType: String
cause
Information pertaining to what caused the error where availableType: ErrorInfo
href
Ably may additionally include a URL to get more help on this errorType: String

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

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

Properties

data
The presence update payload, if provided
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 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.

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()); }); });
Copied!

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

items
contains a page of results; for example, an array of Message or PresenceMessage objects for a channel history requestType: Array<>
statusCode
the HTTP status code of the responseType: Number
success
whether the HTTP status code indicates success. This is equivalent to 200 <= statusCode < 300Type: Boolean
headers
the headers of the responseType: Object
errorCode
the error code if the X-Ably-Errorcode HTTP header is sent in the responseType: Int
errorMessage
the error message if the X-Ably-Errormessage HTTP header is sent in the responseType: String

Methods

first(callback(ErrorInfo err, HttpPaginatedResponse resultPage))

Returns a new HttpPaginatedResponse 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, HttpPaginatedResponse resultPage))

Returns a new HttpPaginatedResponse loaded with the next page of results. If there are no further pages, then null is returned.

Example

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

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

Properties

token
The Ably Token itself. A typical Ably Token string may appear like {{TOKEN}}Type: String
expires
The time (in milliseconds since the epoch) at which this token expiresType: Integer
issued
The time (in milliseconds since the epoch) at which this token was issuedType: Integer
capability
The capability associated with this Ably Token. The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilitiesType: String
clientId
The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID. The client is then considered to be an identified clientType: String

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

json
a TokenDetails-like deserialized object or JSON stringified TokenDetails.Type: Object, String

Returns

A TokenDetails object

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

Properties

keyName
The key name of the key against which this request is made. The key name is public, whereas the key secret is privateType: String
ttl
Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the returned Ably Token will be less than or equal to this value depending on application settings and the attributes of the issuing key.Type: Integer
timestamp
The timestamp of this request in millisecondsType: Integer
capability
Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilitiesType: String
clientId
The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to perform operations on behalf of that client IDType: String
nonce
An opaque nonce string of at least 16 charactersType: String
mac
The Message Authentication Code for this requestType: String

TokenRequest.fromJson(String json) β†’ TokenRequest

A static factory method to create a TokenRequest from a deserialized TokenRequest-like object or a JSON stringified TokenRequest/span><span lang=β€œflutter”>map. 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

json
a TokenRequest-like deserialized object or JSON stringified TokenRequest.Type: Object, String

Returns

A TokenRequest 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.

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 and Python however uses under_score case instead of the default camelCase in most languages, so please bear that in mind.

Properties

unit
the length of the interval that this statistic covers, such as 'minute', 'hour', 'day', 'month'.Type: String
intervalId
the UTC time at which the time period covered by this Stats object starts. For example, an interval ID value of β€œ2018-03-01:10β€³ in a Stats object whose unit is day would indicate that the period covered is β€œ2018-03-01:10 .. 2018-03-01:11β€³. All Stats objects, except those whose unit is minute, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the unit by looking at the resolution of the intervalId. Stats objects covering an individual minute will have an interval ID indicating that time; for example β€œ2018-03-01:10:02β€³.Type: String
all
aggregate count of both inbound and outbound message statsType: MessageTypes
apiRequests
breakdown of API requests received via the Ably REST APIType: RequestCount
channels
breakdown of channel related stats such as min, mean and peak channelsType: ResourceCount
connections
breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connectionsType: ConnectionTypes
inbound
statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messagesType: MessageTraffic
outbound
statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messagesType: MessageTraffic
persisted
messages persisted and later retrieved via the history APIType: MessageTypes
tokenRequests
breakdown of Ably Token requests received via the Ably REST API.Type: RequestCount
push
Detailed stats on push notifications, see our Push documentation for more detailsType: PushStats

Properties

authCallback
A function which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. See our authentication documentation for details of the Ably TokenRequest format and associated API calls.Type: Callable
authUrl
A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.Type: String
authMethod
GET The HTTP verb to use for the request, either GET or POSTType: String
authHeaders
A set of key value pair headers to be added to any request made to the authUrl. Useful when an application requires these to be added to validate the request or implement the response. Type: Object
authParams
A set of key value pair params to be added to any request made to the authUrl. When the authMethod is GET, query params are added to the URL, whereas when authMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.Type: Object
tokenDetails
An authenticated TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Use this option if you wish to use Token authentication. Read more about Token authenticationType: TokenDetails
key
Optionally the API key to use can be specified as a full key string; if not, the API key passed into ClientOptions when instancing the Realtime or REST library is usedType: String
queryTime
false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.Type: Boolean
token
An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the token property of a TokenDetails component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Read more about Token authenticationType: String, TokenDetails or TokenRequest

Properties

key
The full key string, as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authenticationType: String
token
An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the token property of a TokenDetails component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Read more about Token authenticationType: String, TokenDetails or TokenRequest
authCallback
A function which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. See our authentication documentation for details of the Ably TokenRequest format and associated API calls.Type: Callable
authUrl
A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.Type: String
authMethod
GET The HTTP verb to use for the request, either GET or POSTType: String
authHeaders
A set of key value pair headers to be added to any request made to the authUrl. Useful when an application requires these to be added to validate the request or implement the response. Type: Object
authParams
A set of key value pair params to be added to any request made to the authUrl. When the authMethod is GET, query params are added to the URL, whereas when authMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.Type: Object
tokenDetails
An authenticated TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Use this option if you wish to use Token authentication. Read more about Token authenticationType: TokenDetails
tls
true A boolean value, indicating whether or not a TLS (β€œSSLβ€œ) secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. Find out more about TLSType: Boolean
clientId
A client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientId specified here conflicts with the clientId implicit in the token. Find out more about client identitiesType: String
useTokenAuth
false When true, forces Token authentication to be used by the library. Please note that if a clientId is not specified in the ClientOptions or TokenParams, then the Ably Token issued will be anonymous. Type: Boolean
environment
null Enables enterprise customers to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our platform customization guide for more details.Type: String
idempotentRestPublishing
false When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.Type: Boolean
fallbackHosts
[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com] An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the fallback host functionality is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.Type: String []
transportParams
Optional. Can be used to pass in arbitrary connection parameters, such as heartbeatInterval and remainPresentForType: Object
useBinaryProtocol
true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. Find out more about the benefits of binary encodingType: Boolean
queueMessages
true If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditionsType: Boolean
echoMessages
true If false, prevents messages originating from this connection being echoed back on the same connectionType: Boolean
autoConnect
true By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the connect methodType: Boolean
queryTime
false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.Type: Boolean
defaultTokenParams
When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequestsType: TokenParams
disconnectedRetryTimeout
15,000ms When the connection enters the DISCONNECTED state, after this delay in milliseconds, if the state is still DISCONNECTED, the client library will attempt to reconnect automaticallyType: Integer
suspendedRetryTimeout
30,000ms When the connection enters the SUSPENDED state, after this delay in milliseconds, if the state is still SUSPENDED, the client library will attempt to reconnect automaticallyType: Integer

Channel options are used for configuring encryption.

Properties

Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an exampleType: CipherParams

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.

Attributes

current
the new current stateType: ChannelState
previous
the previous state. (for the update event, this will be equal to the current state)Type: ChannelState
event
the event that triggered this state changeType: ChannelEvent
reason
an ErrorInfo containing any information relating to the transitionType: ErrorInfo
resumed
a boolean indicated whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.Type: Boolean

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

algorithm
AES The name of the algorithm in the default system provider, or the lower-cased version of it; eg β€œaes” or β€œAESβ€œType: String
keyLength
256 The key length in bits of the cipher, either 128 or 256Type: Integer
mode
CBC The cipher modeType: String

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

current
the new stateType: State String
previous
the previous state. (for the update event, this will be equal to the current state)Type: State String
event
the event that triggered this state changeType: ConnectionEvent
reason
an ErrorInfo containing any information relating to the transitionType: ErrorInfo
retryIn
Duration upon which the library will retry a connection where applicable, as millisecondsType: Integer

Properties

capability
JSON stringified capability of the Ably Token. If the Ably Token request is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. Find our more about how to use capabilities to manage access privileges for clients. Type: String
clientId
A client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientId specified here conflicts with the clientId implicit in the token. Find out more about client identitiesType: String
nonce
An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected.Type: String
timestamp
The timestamp (in milliseconds since the epoch) of this request. timestamp, in conjunction with the nonce, is used to prevent requests for Ably Token from being replayed.Type: Integer
ttl
1 hour Requested time to live for the Ably Token being created in milliseconds When omitted, the Ably REST API default of 60 minutes is applied by AblyType: Integer (milliseconds)
Data types
v2.0