API v 1.1
JavaScript

Constructor

The Ably Realtime library constructor is overloaded allowing it to be instantiated using a ClientOptions object, or more simply using a string containing an API key or Token, as shown below:

new Ably.Realtime(ClientOptions clientOptions)

This will instantiate the library using the specified ClientOptions.

new Ably.Realtime(String keyOrTokenId)

This will instantiate the Realtime library with the provided API key or Token ID string.

The Realtime constructor is used to instantiate the library. The Realtime library may be instantiated multiple times with the same or different ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.

The Realtime library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on authentication.

Basic Authentication

You can pass a full-length API key in as ClientOptions#key (or just straight into the constructor instead of a ClientOptions instance), as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or if you want to be able to request Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a key does not necessarily mean that the library will use Basic auth; it is also able to create and sign Ably TokenRequests, and can use token authentication for itself if it needs to or if ClientOptions#useTokenAuth is enabled.

Token Authentication

The ClientOptions#token option takes a token string or tokenDetails object, which may have been obtained from some other instance that requested the Ably Token. This option is rarely used in production since tokens are short-lived, so generally you would not start with a token without the means to refresh it. The authUrl and authCallback options allow the library to request new Ably-compatible tokens or Ably TokenRequests as it needs to; using these options allows the library to be instantiated without a key or token, and an initial token will be obtained automatically when required.

Read more on authentication.

The Realtime client exposes the following public attributes:

A reference to the Auth authentication object configured for this client library.

A reference to the Push object in this client library.

Channels is a reference to the Channel collection instance for this library indexed by the channel name. You can use the Get method of this to get a Channel instance. See channels and messages for more information.

A reference to the Connection object for this library instance.

connect()

Explicitly calling connect is unnecessary unless the ClientOptions autoConnect is disabled. This method calls connection.connect() and causes the connection to open, entering the connecting state.

close()

This calls connection.close() and causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to connect().

stats(Object options, callback(ErrorInfo err, PaginatedResult<Stats> results))

This call queries the REST /stats API and retrieves your application’s usage statistics. A PaginatedResult is returned, containing an array of Stats for the first page of results. PaginatedResult objects are iterable providing a means to page through historical statistics. See an example set of raw stats returned via the REST API.

See statistics for more information.

Parameters

options
an optional object containing the query parameters
callback
is a function of the form: function(err, result)

options parameters

The following options, as defined in the REST /stats API endpoint, are permitted:

start
beginning of time earliest time in milliseconds since the epoch for any stats retrievedType: Long
end
current time latest time in milliseconds since the epoch for any stats retrievedType: Long
direction
backwards forwards or backwardsType: String
limit
100 maximum number of stats to retrieve up to 1,000Type: Integer
unit
minute minute, hour, day or month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the queryType: String

time(callback(ErrorInfo err, Number time))

Obtains the time from the Ably service as milliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably TokenRequests with a more accurate timestamp should use the queryTime clientOptions instead of this method).

request(String method, String path, Object params, Object body, Object headers, callback(ErrorInfo err, HttpPaginatedResponse results))

Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to handle authentication, paging, fallback hosts, MsgPack and JSON support, etc. themselves.

Parameters

method
either get, post, put, patch or delete.Type: String
path
the path to query.Type: String
params
(optional) any querystring parameters needed.Type: Object
body
(optional; for post, put and patch methods) the body of the request, as anything that can be serialized into JSON, such as an Object or Array.Type: Serializable
headers
(optional) any headers needed. If provided, these will be mixed in with the default library headers.Type: Object

Example

JavaScript
rest.request( 'get', '/channels/someChannel/messages', {limit: 1, direction: 'forwards'}, null, null, function(err, response) { if(err) { console.log('An error occurred; err = ' + err.toString()); } else { console.log('Success! status code was ' + response.statusCode); console.log(response.items.length + ' items returned'); if(response.hasNext()) { response.next(function(err, nextPage) { console.log(nextPage.items.length + ' more items returned'); }); } } });
Copied!

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 an authentication callback example or 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 anonymousType: 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
recover
This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See connection state recovery for further informationType: String, Callable
closeOnUnload
true When true, the client library will automatically send a close request to Ably whenever the window beforeunload event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the channel will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the close method of the Connection object, Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid “twitchy” presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutesType: 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

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

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