API Version: v1.2
Realtime Client Library API

Using the Realtime library

The Realtime library when initialized attempts to establish and maintain a single connection to the Ably realtime service. This library extends the REST library to provide all REST API functionality including the authentication API. Whereas the Ably REST API is stateless, the Realtime API maintains connection and channel state.

The Ably Realtime client library is available for most popular languages and platforms with a consistent API across all platforms. You can view this documentation with your preferred language API and code examples using the language selector navigation above. If your preferred language is not listed in the language selector, we recommend you download a library in your preferred language and use this documentation as an API reference.

The Realtime library for browser JavaScript environments should be loaded from the Ably CDN as follows:

<script lang="text/javascript" src="https://cdn.ably.io/lib/ably.min-1.js"></script>

You can also obtain the library as an NPM module, or download the source directly from Github

The script and module both contain the Realtime and REST libraries as well as all their dependencies. To instantiate the Realtime library:

var realtime = new Ably.Realtime({ key: apiKey });

When including the client library from our CDN, we recommend you lock into major version 1 of the library. According to the semantic versioning scheme we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version 1 of the library by including https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e 1.*.*). If you want to lock into minor version 1.1 and receive all patch fixes automatically (i.e. 1.1.*), then use https://cdn.ably.io/lib/ably.min-1.1.js. Additionally, the .min suffix can be dropped if you want the non-minified version for debugging.

View a complete list of the JavaScript library releases

The Realtime library for Node.js is suitable for clients and servers and is hosted on Github and is obtainable as an NPM module directly from npm. Install with:

npm install ably

The Ably Node.js module contains both the REST and Realtime libraries; each is exported separately by the module. To instantiate the Realtime library:

var Ably = require('ably');
var realtime = new Ably.Realtime({ key: apiKey });

The Realtime library for Ruby hosted on Github and is published as a RubyGem and can be installed as follows:

gem install ably

If using bundler, simply add the following to your Gemfile and run bundle install:

gem 'ably'

The Ably Ruby gem contains both the REST and Realtime libraries; each is namespaced separately by the gem. The Realtime library must be run within an EventMachine reactor which provides an asynchronous evented framework for the library to run within. To instantiate the Realtime library:

EventMachine.run do
  ably = Ably::Realtime.new(key: api_key)
end

If you are using Ably in your Rails or Sinatra apps, you probably want to be using the Ably REST library that offers a synchronous API and has no dependency on EventMachine.

The Realtime library for Java and Android is hosted on Github and can be used by adding one line to build.gradle dependencies section.

For Java applications:

compile 'io.ably:ably-java:1.2.0'

For Android apps:

compile 'io.ably:ably-android:1.2.0'

In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that. Follow links to get the latest stable release for Java and Android.

Ensure the library is included in your classpath as follows:

import io.ably.lib.types.*;
import io.ably.lib.realtime.*;
ClientOptions options = new ClientOptions(apiKey);
AblyRealtime realtime = new AblyRealtime(options);

The Realtime library for .Net is available as a Nuget Package. Open the nuget console in visual studio and type.

PM> Install-Package ably.io

Alternatively, search for the ‘ably.io’ package through the Nuget UI

using IO.Ably;

ClientOptions clientOptions = new ClientOptions("<API Key>");
AblyRealtime realtime = new AblyRealtime(clientOptions);

The Ably library is hosted on Github and is available as a CocoaPod. Add this line to your application’s Podfile:

pod 'Ably'

And install with pod install. Then in your files:

#import "Ably/Ably.h"

ARTRealtime realtime = [[ARTRealtime alloc] initWithKey:apiKey];
import Ably

let realtime = ARTRealtime(key: apiKey)

Note: Since version 1.0.8, the iOS client libraries are thread-safe. Check the README for details.

The Ably library is hosted on Github and is available as a Flutter plugin. Update your pubspec.yaml with appropriate package version:

dependencies:
  # ...
  ably-flutter: [version]
  # ...

Now, import the package into your Dart file.

import 'package:ably_flutter/ably_flutter.dart' as ably;

View our client library SDKs feature support matrix to see the list of all the available features.

The supported client options are described below.

Tutorials

If you would like to see examples of using the Ably Realtime client library, then we recommend you take a look at our Realtime tutorials.

Realtime API ReferenceRealtime::Client API reference

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)Ably::Realtime.new(ClientOptions client_options)new io.ably.lib.AblyRealtime(ClientOptions clientOptions)new AblyRealtime(ClientOptions clientOptions)(instancetype)initWithOptions:(ARTClientOptions *)options;init(options: ARTClientOptions)ably.Realtime(options: ClientOptions clientOptions)

This will instantiate the library using the specified ClientOptions.

This will instantiate the library and create a new Ably::Realtime::Client using the specified ClientOptions.

new Ably.Realtime(String keyOrTokenId)Ably::Realtime.new(String key_or_token_id)new io.ably.lib.AblyRealtime(String keyOrTokenIdString)new AblyRealtime(string key)(instancetype)initWithKey:(NSString *)key
(instancetype)initWithToken:(NSString *)tokeninit(key: String)
init(token: String)ably.Realtime(key: String key)

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.

Authentication

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#keyClientOptions#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 keyKey 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 authCallbackAuthUrl and AuthCallback:auth_url and :auth_callback 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 tokenKey or Token, and an initial token will be obtained automatically when required.

Read more on authentication.

AblyRealtime PropertiesAbly.Realtime Propertiesio.ably.lib.AblyRealtime MembersAbly::Realtime::Client AttributesARTRealtime Properties

The Realtime client exposes the following public attributesmembersproperties:

authAuth

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

push

A reference to the Push object in this client library.

device

A reference to the LocalDeviceARTLocalDevice object.

channelsChannels

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.

connectionConnection

A reference to the Connection object for this library instance.

rest_client

A reference to the REST Client configured with the same ClientOptions. The Realtime library is a super-set of the REST library, however accessing methods in the REST library, unlike the Realtime library, are blocking operations.

AblyRealtime MethodsAbly.Realtime Methodsio.ably.lib.AblyRealtime MethodsAbly::Realtime::Client MethodsARTRealtime Methods

connectConnect

connect()Deferrable connect → yields Connectionvoid connect()void Connect()

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

Returns

A Deferrable object is returned from this method.

On successfully connecting to Ably, the registered success callbacks for the Deferrable and any block provided to this method yields a Connection object.

Failure to connect will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

closeClose

close()Deferrable close → yields Connectionvoid close()void Close()

This calls connection.close()connection.closeconnection.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()connectConnect().

Returns

A Deferrable object is returned from this method.

On successfully closing the connection, the registered success callbacks for the Deferrable and any block provided to this method yields a Connection object.

Failure to close the connection will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

statsStats

stats(Object options, callback(ErrorInfo err, PaginatedResult<Stats> results))Deferrable stats(Hash options) → yields PaginatedResult<Stats>PaginatedResult<Stats> stats(Param[] options)stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult<ARTStats>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult<Stats>> StatsAsync(StatsRequestParams query)

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

optionsquery
an optional objectHashARTStatsQueryStatsRequestParamsParam[] array containing the query parameters
callback
is a function of the form: function(err, result)
&block
yields a PaginatedResult<Stats> object
callback
called with a ARTPaginatedResult<ARTStats> object or an error

options parametersARTStatsQuery propertiesStatsRequestParams properties

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

start:startStart
beginning of time earliest DateTimeOffset or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset
end:endEnd
current time latest DateTimeOffset or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset
direction:directionDirection
backwards :forwards or :backwards
Type: StringSymbolDirection enum
limit:limitLimit
100 maximum number of stats to retrieve up to 1,000
Type: Integer
unit:unitUnit
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 query
Type: StringARTStatsGranularitySymbolStatsIntervalGranularity enum

Callback result

On success, result contains a PaginatedResult encapsulating an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

On failure to retrieve stats, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation.

Returns

On success, the returned PaginatedResult encapsulates an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

Failure to retrieve the stats will raise an AblyException

Returns

Returns a Task<PaginatedResult> which needs to be awaited.

On success, the returned PaginatedResult encapsulates an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using NextAsync and FirstAsync methods.

Failure to retrieve the stats will raise an AblyException

Returns

A Deferrable object is returned from the stats method.

On success, the registered success callbacks for the Deferrable and any block provided to the method yields a PaginatedResult that encapsulates an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

Failure to retrieve the stats will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

timeTime

time(callback(ErrorInfo err, Number time))Deferrable time → yields Timelong time()Task TimeAsync()time(callback: (NSDate?, NSError?) → Void)

Obtains the time from the Ably service as a Time objecta DateTimeOffset objectmilliseconds 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).

Callback result

On success, time is a number containing the number of milliseconds since the epoch.

On failure to retrieve the Ably server time, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation.

Returns

On success, milliseconds since the epoch is returned.

Failure to retrieve the Ably server time will raise an AblyException.

Returns

A Task<DateTimeOffset> is returned from this method.

When awaited on success it will return the server time converted to a DateTimeOffset.

Failure to retrieve the Ably server time will raise an AblyException.

Returns

A Deferrable object is returned from this method.

On success, the registered success callbacks for the Deferrable and any block provided to the method yields a Time object.

Failure to retrieve the Ably server time will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

requestRequest

request(String method, String path, Object params, Object body, Object headers, callback(ErrorInfo err, HttpPaginatedResponse results))HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)publish(method=String, path=String, params=Object, body=Object, headers=Object)HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)Task<HttpPaginatedResponse> Request(string method, string path, Dictionary<string, string> requestParams, JToken body, Dictionary<string, string> headers)request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: (ARTHttpPaginatedResponse, ARTErrorInfo?) → Void)HTTPPaginatedResponse Request(method string, path string, params PaginateParams, body interface, headers http.Header)

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: Stringstring
path
the path to query.
Type: Stringstring
params
(optional) any querystring parameters needed.
Type: ObjectPaginateParamsDictionary<string, string>
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.a JToken.
Type: SerializableinterfaceJToken
headers
(optional) any headers needed. If provided, these will be mixed in with the default library headers.
Type: Objecthttp.HeaderDictionary<string, string>

Callback result

On successfully receiving a response from Ably, results contains an HttpPaginatedResponseARTHttpPaginatedResponse containing the statusCode of the response, a success boolean (equivalent to whether the status code is between 200 and 299), headers, and an items array containing the current page of results. It supports pagination using next and first methods, identically to PaginatedResult.

On failure to obtain a response, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an err).

Returns

On successfully receiving a response from Ably, the returned HttpPaginatedResponse contains a status_codestatusCode and a success boolean, headers, and an items array containing the current page of results. It supports pagination using next and first methods, identically to PaginatedResult.

Failure to obtain a response will raise an AblyException. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception).

Returns

The method is asynchronous and return a Task that has to be awaited to get the result.

On successfully receiving a response from Ably, the returned HttpPaginatedResponse containing the StatusCode and a Success boolean, Headers, and an Items array containing the current page of results. HttpPaginatedResponse supports pagination using NextAsync and FirstAsync methods.

Failure to obtain a response will raise an AblyException. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception).

Example

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');
        });
      }
    }
  });
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');
        });
      }
    }
  });

ClientOptionsARTClientOptionsio.ably.types.ClientOptionsIO.Ably.ClientOptionsably.ClientOptions

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:

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:

ClientOptions is a associative array and is used in the Ably\AblyRealtime constructor’s options argument. The following named keys and values can be added to the associative array:

ARTClientOptions is used in the AblyRealtime constructor’s options argument.

PropertiesMembersAttributesKeyword arguments

keyKey: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 authentication
Type: String
tokenToken:token
An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the tokenToken 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 authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type: String, TokenDetails or TokenRequest
authCallbackAuthCallbackauth_callback:auth_callback
A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) 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: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>
authUrlAuthUrl:auth_urlauth_url
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: StringUriNSURL
authMethodAuthMethodauth_method:auth_method
GET:get The HTTP verb to use for the request, either GET:get or POST:post
Type: StringSymbolHttpMethod
authHeadersAuthHeadersauth_headers:auth_headers
A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an authorization key, then withCredentials will be set on the xhr request.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>Map<String, String>
authParamsAuthParams:auth_paramsauth_params
A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is GET, query params are added to the URL, whereas when authMethodAuthMethod 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: ObjectHashAssociative ArrayParam[]Dictionary<string, string>NSArray<NSURLQueryItem *>[NSURLQueryItem]/Array<NSURLQueryItem>Map<String, String>
tokenDetailsTokenDetailstoken_details:token_details
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 authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails
tlsTls: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 TLS
Type: Boolean
clientIdClientIdclient_id:client_id
A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId 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 clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_id specified here conflicts with the clientIdclient_idClientId implicit in the token. Find out more about client identities
Type: String
useTokenAuthUseTokenAuthuse_token_auth:use_token_auth
false When true, forces Token authentication to be used by the library. Please note that if a client_idclientId is not specified in the ClientOptions or TokenParams, then the Ably Token issued will be anonymous.
Type: Boolean
environmentEnvironment:environment
nullNullNonenil 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
idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing
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
fallbackHostsFallbackHostsfallback_hosts:fallback_hosts
[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 []
transportParamsTransportParamstransport_params:transport_params
Optional. Can be used to pass in arbitrary connection parameters.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>Map<String, String>
log
Parameters to control the log output of the library. The supplied value must be an object that may contain one or both of the following entries:

  • level: a number controlling the verbosity of the output. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (abbreviated debug output), and 4 (full debug output).

  • handler: a function to handle each line of log output. If handler is not specified, console.log is used.


Note that the log level and log handler have global scope in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type: Object
transports
An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: web_socket, xhr, jsonp.The transports available in the Node.js client library are: web_socket, xhr, comet.
Type: String []
logLevel
5 A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the logLevel is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See the logging section of the java library README for more details.
Type: Integer
logHandler
System.out PrintStream A LogHandler interface can be specified to handle each line of log output. If logHandler is not specified, System.out is used. Note that the logHandler is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See the logging section of the java library README for more details.
Type: PrintStream

To set the log level and custom logger sink when using the .Net library, configure the static IO.Ably.Logger class or specify the ClientOptions:

LogLevel
Error This is an enum controlling the verbosity of the output from Debug (maximum) to Error (errors only). A special value of None will silence all logging. Note that the LogLevel is a static variable in the library and will thus not act independently between library instances.
Type: Enum
LoggerSink
IO.Ably.DefaultLoggerSink The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.
LogLevel
LogError This is an enum controlling the verbosity of the output from LogDebug (maximum) to LogError (errors only). A special value of LogNone will silence all logging. Note that the LogLevel is a static variable in the library and will thus not act independently between library instances.
Type: Enum
logLevel
ARTLogLevelWarn An enum controlling the verbosity of the output from ARTLogLevelVerbose to ARTLogLevelNone. A special value of 99 will silence all logging.
Type: ARTLogLevel
logHandler
A ARTLog object can be specified to handle each line of log output. If logHandler is not specified, a default ARTLog instance is used.
Type: ARTLog *
:log_level
:error Log level for the standard Logger that outputs to STDOUT. Can be set to :fatal, :error, :warn, :info, :debug or :none. Alternatively a Logger severity constant can be specified.
Type: Symbol, Logger::SEVERITY
:logger
STDOUT Logger A Ruby Logger compatible object to handle each line of log output. If logger is not specified, STDOUT is used.
Type: Ruby @Logger
logLevel
Log::WARNING A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose);
Type: Integer
logHandler
console.log A function to handle each line of log output. If handler is not specified, console.log is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently.
Type: Function
useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol
false If set to true, will enable the binary protocol (MessagePack) if it is supported. It’s disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supportedNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type: Boolean
logExceptionReportingUrl
Defaults to a string value for an Ably error reporting Data Source Name.
Type: String
queueMessagesQueueMessages:queue_messages
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 conditions
Type: Boolean
echoMessagesEchoMessages:echo_messages
true If false, prevents messages originating from this connection being echoed back on the same connection
Type: Boolean
autoConnectAutoConnect:auto_connect
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 method
Type: 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 information
Type: 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 minutes
Type: Boolean
recoverRecover:recover
This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection’s recoveryKeyrecovery_key. This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See connection state recovery for further information and example code
Type: String
queryTimeQueryTime:query_time
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
defaultTokenParamsDefaultTokenParams:default_token_params
When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests
Type: TokenParams
disconnectedRetryTimeoutDisconnectedRetryTimeout:disconnected_retry_timeout
15,000ms15s When the connection enters the DISCONNECTED state, after this delay in millisecondsin secondsas a NSTimeInterval, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically
Type: IntegerNSTimeInterval
suspendedRetryTimeoutSuspendedRetryTimeout:suspended_retry_timeout
30,000ms30s When the connection enters the SUSPENDED state, after this delay in millisecondsin secondsas a NSTimeInterval, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
Type: IntegerNSTimeInterval

Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.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 and Python however uses under_score case instead of the default camelCase in most languages, so please bear that in mind.

PropertiesMembersAttributesKeyword arguments

unit
the length of the interval that this statistic covers, such as :minute, :hour, :day, :monthMinute, Hour, Day, MonthStatGranularityDay, StatGranularityMonth'minute', 'hour', 'day', 'month'.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString
interval_granularityintervalGranularity
Deprecated alias for unit; scheduled to be removed in version 2.x client library versions.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString
intervalIdinterval_idIntervalId
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
interval_timeIntervalTime
A TimeDateTimeDateTimeOffset object representing the parsed intervalIdinterval_idIntervalId (the UTC time at which the time period covered by this Stats object starts)
Type: TimeDateTimeDateTimeOffset
allAll
aggregate count of both inbound and outbound message stats
Type: MessageTypes
apiRequestsapi_requestsApiRequests
breakdown of API requests received via the Ably REST API
Type: RequestCount
channelsChannels
breakdown of channel related stats such as min, mean and peak channels
Type: ResourceCount
connectionsConnections
breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections
Type: ConnectionTypes
inboundInbound
statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages
Type: MessageTraffic
outboundOutbound
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 messages
Type: MessageTraffic
persistedPersisted
messages persisted and later retrieved via the history API
Type: MessageTypes
tokenRequeststoken_requestsTokenRequests
breakdown of Ably Token requests received via the Ably REST API.
Type: RequestCount
pushPush
Detailed stats on push notifications, see our Push documentation for more details
Type: PushStats

ARTStatsGranularity

ARTStatsGranularity is an enum specifying the granularity of a ARTStats interval.

typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
    ARTStatsGranularityMinute,
    ARTStatsGranularityHour,
    ARTStatsGranularityDay,
    ARTStatsGranularityMonth
};
enum ARTStatsGranularity : UInt {
    case Minute
    case Hour
    case Day
    case Month
}

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

public enum StatsGranularity
{
    Minute,
    Hour,
    Day,
    Month
}

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.

PropertiesMembersAttributesAttributes

itemsItems
contains a page of results (for example an Array of Message or PresenceMessage objects for a channel history request).
Type: Array<>Type: List<>
statusCodestatus_codeStatusCode
the HTTP status code of the response
Type: Number
successSuccess
whether that HTTP status code indicates success (equivalent to 200 <= statusCode < 300)
Type: Boolean
headersHeaders
the response’s headers
Type: Object

Methods

firstFirst

first(callback(ErrorInfo err, HttpPaginatedResponse resultPage))HttpPaginatedResponse firstHttpPaginatedResponse first()HttpPaginatedResponse first()Task<HttpPaginatedResponse> FirstAsync()HttpPaginatedResponse first()first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)First() (HttpPaginatedResponse, error)

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.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/realtime/types#http-paginated-response.

hasNextHasNexthas_next?has_next

Boolean hasNext()Boolean has_next?Boolean hasNext()Boolean has_next()Boolean HasNext()Boolean hasNext()Boolean hasNext()HasNext() (bool)

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

isLastIsLastlast?is_last

Boolean isLast()Boolean last?Boolean isLast()Boolean is_last()Boolean IsLast()Boolean isLast()Boolean isLast()IsLast() (bool)

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

nextNext

next(callback(ErrorInfo err, HttpPaginatedResponse resultPage))HttpPaginatedResponse nextHttpPaginatedResponse next()HttpPaginatedResponse next()Task<HttpPaginatedResponse > NextAsync()HttpPaginatedResponse next()next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)Next() (HttpPaginatedResponse, error)

Returns a new HttpPaginatedResponse loaded with the next page of results. If there are no further pages, then nulla blank HttpPaginatedResponse will be returnedNullNonenil is returned. The method is asynchronous and return a Task which needs to be awaited to get the HttpPaginatedResponseWhen 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

io.ably.lib.types.Param

Param is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see Channel#history for an example.

Please note that key and value attributes are always strings. If an Integer or other value type is expected, then you must coerce that type into a String.

Members

key
The key value
Type: String
value
The value associated with the key
Type: String

API reference
Documentation

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.

Support & Help Contact Us
Talk to our technical team

If you're having technical or account issues just get in touch.

Don’t want to chat? Get in touch via our contact page

Try our APIs for free

Our free plan includes

  • 3m messages per month
  • 100 peak connections
  • 100 peak channels
  • Loads of features
Start with a free account