# Constructor

## Constructor 

The Ably Realtime library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](https://ably.com/docs/auth/basic) or [Token](https://ably.com/docs/auth/token), as shown below:

<If lang="javascript,nodejs">

`new Ably.Realtime(ClientOptions clientOptions)`

</If>

<If lang="ruby">

`Ably::Realtime.new(ClientOptions client_options)`

</If>

<If lang="java">

`new io.ably.lib.AblyRealtime(ClientOptions clientOptions)`

</If>

<If lang="csharp">

`new AblyRealtime(ClientOptions clientOptions)`

</If>

<If lang="objc">

`(instancetype)initWithOptions:(ARTClientOptions *)options;`

</If>

<If lang="swift">

`init(options: ARTClientOptions)`

</If>

<If lang="flutter">

`ably.Realtime(options: ClientOptions clientOptions)`

</If>

<If lang="javascript,nodejs,java,swift,objc,csharp,flutter">

This will instantiate the library using the specified [ClientOptions](#client-options).

</If>

<If lang="ruby">

This will instantiate the library and create a new `Ably::Realtime::Client` using the specified [ClientOptions](#client-options).

</If>

<If lang="javascript,nodejs">

`new Ably.Realtime(String keyOrTokenId)`

</If>

<If lang="ruby">

`Ably::Realtime.new(String key_or_token_id)`

</If>

<If lang="java">

`new io.ably.lib.AblyRealtime(String keyOrTokenIdString)`

</If>

<If lang="csharp">

`new AblyRealtime(string key)`

</If>

<If lang="objc">

`(instancetype)initWithKey:(NSString *)key
(instancetype)initWithToken:(NSString *)token`

</If>

<If lang="swift">

`init(key: String)
init(token: String)`

</If>

<If lang="flutter">

`ably.Realtime(key: String key)`

</If>

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`](#client-options) 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](https://ably.com/docs/auth).

#### Basic Authentication

<If lang="javascript,nodejs,ruby,java,swift,objc,flutter,csharp">

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](https://ably.com/dashboard). Use this option if you wish to use [Basic authentication](https://ably.com/docs/auth/basic), or if you want to be able to [request Ably Tokens](https://ably.com/docs/auth/token) without needing to defer to a separate entity to sign [Ably TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#token-request). 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](https://ably.com/docs/api/realtime-sdk/authentication#token-request), and can use token authentication for itself if it needs to or if [`ClientOptions#useTokenAuth`](#client-options) is enabled.

</If>

#### Token Authentication

<If lang="javascript,nodejs,java,swift,objc,flutter">

The [`ClientOptions#token`](#client-options) option takes a `token` string or [`tokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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](#client-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.

</If>

<If lang="csharp">

The [`ClientOptions#token`](#client-options) option takes a `token` string or [tokenDetails](https://ably.com/docs/api/realtime-sdk/types#token-details) 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](#client-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.

</If>

<If lang="ruby">

The [`ClientOptions#token`](#client-options) option takes a `token` string or [tokenDetails](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 [`:auth_url` and `:auth_callback` options](#client-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.

</If>

Read more on [authentication](https://ably.com/docs/auth).

<If lang="objc,swift">

### Thread safety 

The Cocoa SDK makes the following thread safety guarantees:

- All public methods and properties can be safely accessed from any thread, both for reading and writing operations.
- Objects like `ARTTokenDetails` and message data returned by the SDK can be safely read from multiple threads. However, you should not modify these objects after they're created.
- Objects you pass to the library must not be mutated afterwards. Once passed to the SDK, treat them as immutable. You can safely read from them or pass them again, and the library will never modify them.

All internal operations are dispatched to a single serial GCD queue to ensure thread safety within the SDK. You can specify a custom queue for this using `ARTClientOptions.internalDispatchQueue`, but it must be serial to maintain thread safety guarantees.

All callbacks provided by you are dispatched to the main queue by default, allowing you to update UI directly without additional thread switching. You can specify a different queue using `ARTClientOptions.dispatchQueue`. The callback queue must be different from `ARTClientOptions.internalDispatchQueue` to prevent deadlocks. Using the same queue creates circular dependencies where internal operations wait for callbacks, while callbacks wait for the internal queue.

</If>

## <If lang="javascript,nodejs">Ably.Realtime Properties</If><If lang="java">io.ably.lib.AblyRealtime Members</If><If lang="ruby">Ably::Realtime::Client Attributes</If><If lang="objc,swift">ARTRealtime Properties</If><If lang="csharp,flutter">AblyRealtime Properties</If> 

<If lang="ruby,java">

The Realtime client exposes the following public <If lang="ruby">attributes</If><If lang="java">members</If>:

</If>

<If lang="javascript,nodejs,objc,swift,csharp,flutter">

The Realtime client exposes the following public properties:

</If>

### <If lang="csharp">`Auth`</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">`auth`</If> 

A reference to the [Auth](https://ably.com/docs/api/realtime-sdk/authentication) authentication object configured for this client library.

### `push` 

A reference to the [Push](https://ably.com/docs/push) object in this client library.

<If lang="java,swift,objc">

### `device` 

<If lang="java">

A reference to the [LocalDevice](https://ably.com/docs/api/realtime-sdk/push#local-device) object.

</If>

<If lang="objc,swift">

A reference to the [ARTLocalDevice](https://ably.com/docs/api/realtime-sdk/push#local-device) object.

</If>

</If>

### <If lang="csharp">`Channels`</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">`channels`</If> 

[Channels](https://ably.com/docs/api/realtime-sdk/channels#channels-object) is a reference to the [Channel](https://ably.com/docs/channels) collection instance for this library indexed by the channel name. You can use the [Get](https://ably.com/docs/api/realtime-sdk/channels#get) method of this to get a `Channel` instance. See [channels](https://ably.com/docs/channels) and [messages](https://ably.com/docs/channels/messages) for more information.

### <If lang="csharp">`Connection`</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">`connection`</If> 

A reference to the [Connection](https://ably.com/docs/api/realtime-sdk/connection) object for this library instance.

<If lang="ruby">

### `rest_client` 

A reference to the [REST Client](https://ably.com/docs/api/rest-sdk) configured with the same [ClientOptions](#client-options). 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.

</If>

## <If lang="javascript,nodejs">Ably.Realtime Methods</If><If lang="java">io.ably.lib.AblyRealtime Methods</If><If lang="ruby">Ably::Realtime::Client Methods</If><If lang="objc,swift">ARTRealtime Methods</If><If lang="csharp,flutter">AblyRealtime Methods</If> 

### <If lang="csharp">Connect</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">connect</If> 

<If lang="javascript">

`connect(): void`

</If>

<If lang="flutter">

`connect(): void`

</If>

<If lang="ruby">

`Deferrable connect -> yields Connection`

</If>

<If lang="java">

`void connect()`

</If>

<If lang="objc">

`connect(): void`

</If>

<If lang="csharp">

`void Connect()`

</If>

<If lang="swift">

`connect(): void`

</If>

<If lang="javascript,nodejs,java,swift,objc,flutter">

Explicitly calling `connect` is unnecessary unless the [ClientOptions](#client-options) `autoConnect` is disabled. This method calls `connection.connect()` and causes the connection to open, entering the `connecting` state.

</If>

<If lang="ruby">

Explicitly calling `connect` is unnecessary unless the [ClientOptions](#client-options) `auto_connect` is disabled. This method calls `connection.connect` and causes the connection to open, entering the `connecting` state.

</If>

<If lang="csharp">

Explicitly calling `Connect` is unnecessary unless the [ClientOptions](#client-options) `AuthConnect` is disabled. This method calls `connection.Connect()` and causes the connection to open, entering the `connecting` state.

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from this method.

On successfully connecting to Ably, the registered success callbacks for the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to this method yields a [Connection](https://ably.com/docs/api/realtime-sdk/connection) object.

Failure to connect will trigger the errback callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [ErrorInfo](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

### <If lang="csharp">Close</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">close</If> 

<If lang="javascript,nodejs">

`close(): void`

</If>

<If lang="flutter">

`close(): void`

</If>

<If lang="ruby">

`Deferrable close -> yields Connection`

</If>

<If lang="java">

`void close()`

</If>

<If lang="objc">

`close(): void`

</If>

<If lang="csharp">

`void Close()`

</If>

<If lang="swift">

`close(): void`

</If>

<If lang="javascript,nodejs,java,swift,objc,flutter">

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()`.

</If>

<If lang="ruby">

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`.

</If>

<If lang="csharp">

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()`.

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from this method.

On successfully closing the connection, the registered success callbacks for the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to this method yields a [Connection](https://ably.com/docs/api/realtime-sdk/connection) object.

Failure to close the connection will trigger the errback callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [ErrorInfo](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

### <If lang="csharp">Stats</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">stats</If> 

<If lang="javascript">

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

</If>

<If lang="nodejs">

`stats(Object params?): Promise<PaginatedResult<Stats>>`

</If>

<If lang="flutter">

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

</If>

<If lang="ruby">

`Deferrable stats(Hash options) ->; yields PaginatedResult<Stats>;`

</If>

<If lang="java">

`PaginatedResult<Stats> stats(Param[] options)`

</If>

<If lang="swift,objc">

`stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult<ARTStats>?, ARTErrorInfo?) -> Void) throws`

</If>

<If lang="csharp">

`Task<PaginatedResult<Stats>> StatsAsync(StatsRequestParams query)`

</If>

This call queries the [REST `/stats` API](https://ably.com/docs/api/rest-api#stats) and retrieves your application's usage statistics. A [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types#paginated-result) is returned, containing an array of [Stats](#stats-type) for the first page of results. [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types#paginated-result) objects are iterable providing a means to page through historical statistics. [See an example set of raw stats returned via the REST API](https://ably.com/docs/metadata-stats/stats#metrics).

See [statistics](https://ably.com/docs/metadata-stats/stats) for more information.

#### Parameters

<If lang="javascript,nodejs,java,csharp,flutter">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="java,flutter">options</If><If lang="csharp">query</If> | An optional object containing the query parameters<If lang="javascript,nodejs"> used to specify which statistics are retrieved. If not specified the default parameters will be used</If> | <If lang="javascript,nodejs,flutter">Object</If><If lang="java">[`Param[]`](#param)</If><If lang="csharp">`StatsRequestParams`</If> |

</If>

<If lang="ruby">

| Parameter | Description | Type |
|-----------|-------------|------|
| options | An optional object containing the query parameters | Hash |
| &block | Yields a `PaginatedResult<Stats>` object | Block |

</If>

<If lang="swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| query | An optional object containing the query parameters | `ARTStatsQuery` |
| callback | Called with a [ARTPaginatedResult](#paginated-result)&lt;[ARTStats](https://ably.com/docs/api/rest-sdk/types#stats)&gt; object or an error | Callback |

</If>

#### <If lang="java,flutter,ruby">`options` parameters</If><If lang="objc,swift">`ARTStatsQuery` properties</If><If lang="csharp">`StatsRequestParams` properties</If><If lang="javascript,nodejs">`params` properties</If>

The following options, as defined in the [REST `/stats` API](https://ably.com/docs/api/rest-api#stats) endpoint, are permitted:

| Property | Description | Type | Default |
|----------|-------------|------|---------|
| <If lang="javascript,nodejs,java,swift,objc,flutter">start</If><If lang="ruby">:start</If><If lang="csharp">Start</If> | Earliest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any stats retrieved | <If lang="java">`Long`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="javascript,nodejs">`Number`</If><If lang="swift,objc,flutter">`Long`</If> | beginning of time |
| <If lang="javascript,nodejs,java,swift,objc,flutter">end</If><If lang="ruby">:end</If><If lang="csharp">End</If> | Latest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any stats retrieved | <If lang="java">`Long`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="javascript,nodejs">`Number`</If><If lang="swift,objc,flutter">`Long`</If> | current time |
| <If lang="javascript,nodejs,java,swift,objc,flutter">direction</If><If lang="ruby">:direction</If><If lang="csharp">Direction</If> | <If lang="ruby">`:forwards` or `:backwards`</If><If lang="javascript,nodejs,java,swift,objc,flutter">`forwards` or `backwards`</If><If lang="csharp">`forwards` or `backwards`</If> | <If lang="javascript,nodejs,java,swift,objc,flutter">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`Direction` enum</If> | backwards |
| <If lang="javascript,nodejs,java,swift,objc,flutter">limit</If><If lang="ruby">:limit</If><If lang="csharp">Limit</If> | Maximum number of stats to retrieve up to 1,000 | <If lang="java">`Integer`</If><If lang="javascript,nodejs">`Number`</If><If lang="ruby,csharp,swift,objc,flutter">`Integer`</If> | 100 |
| <If lang="javascript,nodejs,java,swift,objc,flutter">unit</If><If lang="ruby">:unit</If><If lang="csharp">Unit</If> | <If lang="ruby">`:minute`, `:hour`, `:day` or `:month`.</If><If lang="javascript,nodejs,java,swift,objc,flutter">`minute`, `hour`, `day` or `month`.</If><If lang="csharp">`minute`, `hour`, `day` or `month`.</If> 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 | <If lang="java">`String`</If><If lang="javascript,nodejs">[`StatsIntervalGranularity`](https://ably.com/docs/api/realtime-sdk/types#stats-granularity)</If><If lang="objc,swift">[`ARTStatsGranularity`](#stats-granularity)</If><If lang="ruby">`Symbol`</If><If lang="csharp">[`StatsIntervalGranularity`](https://ably.com/docs/api/realtime-sdk/types#stats-granularity) enum</If> | minute |

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/types#paginated-result) object containing an array of [`Stats`](https://ably.com/docs/api/realtime-sdk/types#stats) objects. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object.

</If>

<If lang="objc,swift">

#### Callback result

On success, `result` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Stats`](https://ably.com/docs/api/realtime-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

On failure to retrieve stats, `err` contains an [`ErrorInfo`](#error-info) object with an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

<If lang="java">

#### Returns

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Stats`](https://ably.com/docs/api/realtime-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

Failure to retrieve the stats will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception)

</If>

<If lang="csharp">

#### Returns

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

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Stats`](https://ably.com/docs/api/realtime-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods.

Failure to retrieve the stats will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception)

</If>

<If lang="ruby">

#### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the stats method.

On success, the registered success callbacks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to the method yields a [PaginatedResult](#paginated-result) that encapsulates an array of [`Stats`](https://ably.com/docs/api/realtime-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

Failure to retrieve the stats will trigger the errback callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [`ErrorInfo`](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

### <If lang="csharp">Time</If><If lang="javascript,nodejs,ruby,java,swift,objc,flutter">time</If> 

<If lang="javascript,nodejs">

`time(): Promise<Number>`

</If>

<If lang="flutter">

`time(callback(ErrorInfo err, Number time))`

</If>

<If lang="ruby">

`Deferrable time -> yields Time`

</If>

<If lang="java">

`long time()`

</If>

<If lang="csharp">

`Task<DateTimeOffset>; TimeAsync()`

</If>

<If lang="objc,swift">

`time(callback: (NSDate?, NSError?) -> Void)`

</If>

<If lang="ruby">

Obtains the time from the Ably service as a `Time` object. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [clientOptions](#client-options) instead of this method).

</If>

<If lang="csharp">

Obtains the time from the Ably service as a `DateTimeOffset` object. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [clientOptions](#client-options) instead of this method).

</If>

<If lang="javascript,nodejs,java,swift,objc,flutter">

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](https://ably.com/docs/api/realtime-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [clientOptions](#client-options) instead of this method).

</If>

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an [ErrorInfo](https://ably.com/docs/api/realtime-sdk/types#error-info) object.

</If>

<If lang="objc,swift">

#### 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](#error-info) object with an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

<If lang="java">

#### Returns

On success, milliseconds since the epoch is returned.

Failure to retrieve the Ably server time will raise an [AblyException](#ably-exception).

</If>

<If lang="csharp">

#### 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](#ably-exception).

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from this method.

On success, the registered success callbacks for the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#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](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [ErrorInfo](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) documentation.

</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">request</If><If lang="csharp">Request</If> 

<If lang="javascript,nodejs">

`request(method, path, version, params?, body?, headers?): Promise<HttpPaginatedResponse>`

</If>

<If lang="flutter">

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

</If>

<If lang="ruby">

`HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)`

</If>

<If lang="java">

`HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)`

</If>

<If lang="csharp">

`Task<HttpPaginatedResponse> Request(string method, string path, Dictionary<string, string> requestParams, JToken body, Dictionary<string, string> headers)`

</If>

<If lang="objc,swift">

`request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: (ARTHttpPaginatedResponse, ARTErrorInfo?) -> Void)`

</If>

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

<If lang="javascript,nodejs">

| Parameter | Description | Type |
|-----------|-------------|------|
| method | Either `get`, `post`, `put`, `patch` or `delete` | String |
| path | The path to query | String |
| version | Version of the REST API to use | Number |
| params | (Optional) Any querystring parameters needed | 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` | Serializable |
| headers | (Optional) Any headers needed. If provided, these will be mixed in with the default library headers | Object |

</If>

<If lang="flutter,java,swift,objc,ruby,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| method | Either `get`, `post`, `put`, `patch` or `delete` | <If lang="csharp">string</If><If lang="javascript,nodejs,ruby,java,objc,swift,flutter">String</If> |
| path | The path to query | <If lang="csharp">string</If><If lang="ruby,java,objc,swift,flutter">String</If> |
| params | (Optional) Any querystring parameters needed | <If lang="csharp">`Dictionary<string, string>`</If><If lang="ruby,java,objc,swift,flutter">Object</If> |
| body | (Optional; for `post`, `put` and `patch` methods) The body of the request, as <If lang="csharp">a JToken</If><If lang="ruby,java,objc,swift,flutter">anything that can be serialized into JSON, such as an `Object` or `Array`</If> | <If lang="csharp">JToken</If><If lang="ruby,java,objc,swift,flutter">Serializable</If> |
| headers | (Optional) Any headers needed. If provided, these will be mixed in with the default library headers | <If lang="csharp">`Dictionary<string, string>`</If><If lang="ruby,java,objc,swift,flutter">Object</If> |

</If>

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with the [`HttpPaginatedResponse`](https://ably.com/docs/api/realtime-sdk/types#http-paginated-response) object returned by the HTTP request. The response object will contain an empty or JSON-encodable object. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object.

</If>

<If lang="objc,swift">

#### Callback result

On successfully receiving a response from Ably, `results` contains an <If lang="default">`HttpPaginatedResponse`</If><If lang="objc,swift">`ARTHttpPaginatedResponse`</If> [object](https://ably.com/docs/api/rest-sdk/types#http-paginated-response) 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`](#paginated-result) and [`first`](#paginated-result) methods, identically to [`PaginatedResult`](https://ably.com/docs/api/rest-sdk/types#paginated-result).

On failure to obtain a response, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/rest-sdk/types#error-info) object with an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api#common) 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`).

</If>

<If lang="java,ruby">

#### Returns

On successfully receiving a response from Ably, the returned [`HttpPaginatedResponse`](https://ably.com/docs/api/rest-sdk/types#http-paginated-response) contains a <If lang="ruby,python">`status_code`</If><If lang="default">`statusCode`</If> and a `success` boolean, `headers`, and an `items` array containing the current page of results. It supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods, identically to [`PaginatedResult`](https://ably.com/docs/api/rest-sdk/types#paginated-result).

Failure to obtain a response will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception). (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).

</If>

<If lang="csharp">

#### 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`](https://ably.com/docs/api/rest-sdk/types#http-paginated-response) containing the `StatusCode` and a `Success` boolean, `Headers`, and an `Items` array containing the current page of results. [`HttpPaginatedResponse`](https://ably.com/docs/api/rest-sdk/types#http-paginated-response) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods.

Failure to obtain a response will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception). (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).

</If>

<If lang="javascript,nodejs">

#### Example

<If lang="javascript">

<Code>

```javascript
const response = await rest.request(
  'get',
  '/channels/someChannel/messages',
  3,
  { limit: 1, direction: 'forwards' },
);
console.log('Success! status code was ' + response.statusCode);
console.log(response.items.length + ' items returned');
if (response.hasNext()) {
  const nextPage = await response.next();
  console.log(nextPage.items.length + ' more items returned');
}
```

</Code>

</If>

<If lang="nodejs">

<Code>

```nodejs
const response = await rest.request(
  'get',
  '/channels/someChannel/messages',
  3,
  { limit: 1, direction: 'forwards' },
);
console.log('Success! status code was ' + response.statusCode);
console.log(response.items.length + ' items returned');
if (response.hasNext()) {
  const nextPage = await response.next();
  console.log(nextPage.items.length + ' more items returned');
}
```

</Code>

</If>

### batchPublish 

There are two overloaded versions of this method:

`batchPublish(BatchPublishSpec spec): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>>`

Publishes a [BatchPublishSpec](#batch-publish-spec) object to one or more channels, up to a maximum of 100 channels.

`batchPublish(BatchPublishSpec[] specs): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>[]>`

Publishes one or more [BatchPublishSpec](#batch-publish-spec) objects to one or more channels, up to a maximum of 100 channels.

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| spec | An object describing the messages to be batch published and to which channels | [BatchPublishSpec](#batch-publish-spec) |
| specs | An array of objects describing the messages to be batch published and to which channels | [BatchPublishSpec[]](#batch-publish-spec) |

#### Returns

Returns a promise. On success, the promise is fulfilled with a [BatchResult](#batch-result) object, or an array of [BatchResult](#batch-result) objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as [BatchPublishSuccessResult](#batch-publish-success-result) objects, whilst failures are [BatchPublishFailureResult](#batch-publish-failure-result) objects. If an array of [BatchResult](#batch-result) objects are returned, they are in the same order as the provided [BatchPublishSpec](#batch-publish-spec). On failure, the promise is rejected with an [ErrorInfo](https://ably.com/docs/api/realtime-sdk/types#error-info) object.

### batchPresence 

`batchPresence(String[] channels): Promise<BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>[]>`

Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the [clientId](#client-options) of members and their current [PresenceAction](https://ably.com/docs/api/realtime-sdk/presence#presence-action).

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| channels | An array of one or more channel names, up to a maximum of 100 channels | `String[]` |

#### Returns

Returns a promise. On success, the promise is fulfilled with a [BatchResult](#batch-result) object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as [BatchPresenceSuccessResult](#batch-presence-success-result) objects, whilst failures are [BatchPresenceFailureResult](#batch-presence-failure-result) objects. On failure, the promise is rejected with an [ErrorInfo](https://ably.com/docs/api/realtime-sdk/types#error-info) object.

</If>

## Related types 

### <If lang="swift,objc">ARTClientOptions</If><If lang="java">io.ably.types.ClientOptions</If><If lang="csharp">IO.Ably.ClientOptions</If><If lang="flutter">ably.ClientOptions</If><If lang="javascript,nodejs,ruby">ClientOptions</If> 

<If lang="javascript,nodejs">

`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:

</If>

<If lang="ruby">

`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:

</If>

<If lang="java,objc,swift,csharp,flutter">

<If lang="objc,swift">`ART`</If>`ClientOptions` is used in the `AblyRealtime` constructor's `options` argument.

</If>

#### <If lang="javascript,nodejs">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If><If lang="csharp,swift,objc,flutter">Properties</If>

<If lang="javascript,nodejs">

| Property | Description |
|----------|-------------|
| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` 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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `String` |
| authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
| 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. <If lang="javascript">If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request</If><br />**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<br />**Type:** `Object` |
| tokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| useTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| idempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Object` |
| useBinaryProtocol | <If lang="javascript">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)</If><If lang="nodejs">If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported</If>. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** <If lang="javascript">false</If><If lang="nodejs">true</If> |
| queueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| autoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| logLevel | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output)<br />**Type:** `Integer` |
| logHandler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used<br />**Type:** `Callable` |
| transports | An optional array of transports to use, in descending order of preference. <If lang="javascript">In the browser environment the available transports are: `web_socket`, `xhr_polling`</If><If lang="nodejs">The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet`</If><br />**Type:** `String[]` |
| recover | <If lang="javascript">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](https://ably.com/docs/connect/states) for further information<br />**Type:** `String`, `Callable`</If><If lang="nodejs">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 [`recoveryKey`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String`</If> |
| closeOnUnload | <If lang="javascript">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 connection 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`](https://ably.com/docs/api/realtime-sdk/connection#close) method of the [`Connection object`](https://ably.com/docs/api/realtime-sdk/connection), 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<br />**Type:** `Boolean`<br />**Default:** true</If> |
| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| defaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| disconnectedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
| suspendedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |
| pushServiceWorkerUrl | A URL pointing to a service worker script which is used as the target for web push notifications<br />**Type:** `String` |

</If>

<If lang="csharp">

| Property | Description |
|----------|-------------|
| Key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| Token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `Token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Func<TokenParams, Task<object>>` |
| 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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `Uri` |
| AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `HttpMethod`<br />**Default:** `GET` |
| 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<br />**Type:** `Dictionary<string, string>` |
| 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<br />**Type:** `Dictionary<string, string>` |
| TokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| Tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| UseTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| IdempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| FallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| TransportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Dictionary<string, object>` |
| LogLevel | 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<br />**Type:** `Enum`<br />**Default:** `Error` |
| LoggerSink | The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure<br />**Type:** `ILoggerSink`<br />**Default:** `IO.Ably.DefaultLoggerSink` |
| UseBinaryProtocol | 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 encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| QueueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| AutoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| 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 [`recoveryKey`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String` |
| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| DefaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| DisconnectedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
| SuspendedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |

</If>

<If lang="java">

| Property | Description |
|----------|-------------|
| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
| authCallback | A `TokenCallback` instance 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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `TokenCallback` |
| 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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `String` |
| authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
| 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<br />**Type:** `Param[]` |
| 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<br />**Type:** `Param[]` |
| tokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| useTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** Null |
| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** Null |
| idempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Param[]` |
| logLevel | 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](https://github.com/ably/ably-java/#logging) for more details<br />**Type:** `Integer`<br />**Default:** 5 |
| logHandler | 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](https://github.com/ably/ably-java/#logging) for more details<br />**Type:** `PrintStream`<br />**Default:** `System.out PrintStream` |
| useBinaryProtocol | 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 encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| queueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| autoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| 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 [`recoveryKey`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String` |
| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| defaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| disconnectedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
| suspendedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |

</If>

<If lang="ruby">

| Property | Description |
|----------|-------------|
| :key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| :token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the :token property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 :auth_url or :auth_callback. Read more about [Token authentication](https://ably.com/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
| :auth_callback | A 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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Proc` |
| :auth_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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** String |
| :auth_method | The HTTP verb to use for the request, either `:get` or `:post`<br />**Type:** `Symbol`<br />**Default:** `:get` |
| :auth_headers | A set of key value pair headers to be added to any request made to the :auth_url. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Hash` |
| :auth_params | A set of key value pair params to be added to any request made to the :auth_url. When the :auth_method is `GET`, query params are added to the URL, whereas when :auth_method 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<br />**Type:** `Hash` |
| :token_details | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| :tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| :use_token_auth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| :idempotent_rest_publishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| :fallback_hosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| :transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Hash` |
| :log_level | 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](http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description) can be specified<br />**Type:** `Symbol`, [`Logger::SEVERITY`](http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description)<br />**Default:** `:error` |
| :logger | A [Ruby `Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) compatible object to handle each line of log output. If `logger` is not specified, `STDOUT` is used<br />**Type:** [Ruby `Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html)<br />**Default:** `STDOUT Logger` |
| :use_binary_protocol | 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 encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| :queue_messages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| :echo_messages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| :auto_connect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| :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 [`recovery_key`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String` |
| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| :default_token_params | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| :disconnected_retry_timeout | When the connection enters the `DISCONNECTED` state, after this delay in seconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** Integer<br />**Default:** 15s |
| :suspended_retry_timeout | When the connection enters the `SUSPENDED` state, after this delay in seconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** Integer<br />**Default:** 30s |

</If>

<If lang="swift">

| Property | Description |
|----------|-------------|
| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `NSURL` |
| authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
| 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<br />**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<br />**Type:** `[NSURLQueryItem]/Array<NSURLQueryItem>` |
| tokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| useTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| idempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Object` |
| logLevel | An enum controlling the verbosity of the output from `ARTLogLevelVerbose` to `ARTLogLevelNone`. A special value of 99 will silence all logging<br />**Type:** `ARTLogLevel`<br />**Default:** `ARTLogLevelWarn` |
| 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<br />**Type:** `ARTLog *` |
| useBinaryProtocol | Note: The binary protocol is currently not supported in Swift. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| logExceptionReportingUrl | Defaults to a string value for an Ably error reporting Data Source Name<br />**Type:** `String` |
| queueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| autoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| 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 [`recoveryKey`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String` |
| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| defaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay as a `NSTimeInterval`, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 15,000ms |
| suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay as a `NSTimeInterval`, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 30,000ms |

</If>

<If lang="objc">

| Property | Description |
|----------|-------------|
| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `NSURL` |
| authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
| 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<br />**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<br />**Type:** `NSArray<NSURLQueryItem *>` |
| tokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| useTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
| idempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Object` |
| logLevel | An enum controlling the verbosity of the output from `ARTLogLevelVerbose` to `ARTLogLevelNone`. A special value of 99 will silence all logging<br />**Type:** `ARTLogLevel`<br />**Default:** `ARTLogLevelWarn` |
| 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<br />**Type:** `ARTLog *` |
| useBinaryProtocol | Note: The binary protocol is currently not supported in Objective-C. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| logExceptionReportingUrl | Defaults to a string value for an Ably error reporting Data Source Name<br />**Type:** `String` |
| queueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| autoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| 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 [`recoveryKey`](https://ably.com/docs/api/realtime-sdk/connection#recovery-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](https://ably.com/docs/connect/states) for further information and example code<br />**Type:** `String` |
| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| defaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay as a `NSTimeInterval`, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 15,000ms |
| suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay as a `NSTimeInterval`, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 30,000ms |

</If>

<If lang="flutter">

| Property | Description |
|----------|-------------|
| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](https://ably.com/docs/auth/basic)<br />**Type:** `String` |
| token | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](https://ably.com/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](https://ably.com/docs/auth/token#jwt)). 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](https://ably.com/docs/auth) for details of the Ably TokenRequest format and associated API calls<br />**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`](https://ably.com/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](https://ably.com/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server<br />**Type:** `String` |
| authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
| 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<br />**Type:** `Map<String, String>` |
| 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<br />**Type:** `Map<String, String>` |
| tokenDetails | An authenticated [`TokenDetails`](https://ably.com/docs/api/realtime-sdk/types#token-details) 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 authentication](https://ably.com/docs/auth/token)<br />**Type:** `TokenDetails` |
| tls | 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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
| 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 identities](https://ably.com/docs/auth/identified-clients)<br />**Type:** `String` |
| useTokenAuth | When true, forces [Token authentication](https://ably.com/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](https://ably.com/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
| idempotentRestPublishing | 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<br />**Type:** `Boolean`<br />**Default:** false |
| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here<br />**Type:** `String[]`<br />**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` |
| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](https://ably.com/docs/connect#heartbeats) and [`remainPresentFor`](https://ably.com/docs/presence-occupancy/presence#unstable-connections)<br />**Type:** `Map<String, String>` |
| useBinaryProtocol | 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 encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />**Type:** `Boolean`<br />**Default:** true |
| queueMessages | 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<br />**Type:** `Boolean`<br />**Default:** true |
| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
| autoConnect | 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`](https://ably.com/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](https://ably.com/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](https://ably.com/docs/api/realtime-sdk/authentication#request-token), 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](https://en.wikipedia.org/wiki/Ntpd). 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<br />**Type:** `Boolean`<br />**Default:** false |
| defaultTokenParams | When a [TokenParams](https://ably.com/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](https://ably.com/docs/api/realtime-sdk/types#token-params) |
| disconnectedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
| suspendedRetryTimeout | 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 automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |

</If>

### <If lang="swift,objc">ARTStats</If><If lang="java">io.ably.lib.types.Stats</If><If lang="ruby">Ably::Models::Stats</If><If lang="csharp">IO.Ably.Stats</If><If lang="javascript,nodejs">Stats object</If> 

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](https://ably.com/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard).

#### <If lang="javascript,nodejs,flutter,swift,csharp,obj-c">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

<If lang="flutter">

| Property | Description | Type |
|----------|-------------|------|
| unit | The length of the interval that this statistic covers, such as `'minute'`, `'hour'`, `'day'`, `'month'` | `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" | `String` |
| interval_time | A `Date` object representing the parsed `intervalId` (the UTC time at which the time period covered by this `Stats` object starts) | `Date` |
| all | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| apiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| channels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) |
| connections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) |
| persisted | Messages persisted and later retrieved via the [history API](https://ably.com/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| tokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| push | Detailed stats on push notifications, see [our Push documentation](https://ably.com/push) for more details | `PushStats` |

</If>

<If lang="java">

| Property | Description | Type |
|----------|-------------|------|
| unit | The length of the interval that this statistic covers, such as `'minute'`, `'hour'`, `'day'`, `'month'` | `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" | `String` |
| interval_time | A `Date` object representing the parsed `intervalId` (the UTC time at which the time period covered by this `Stats` object starts) | `Date` |
| all | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| apiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| channels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) |
| connections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) |
| persisted | Messages persisted and later retrieved via the [history API](https://ably.com/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| tokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| push | Detailed stats on push notifications, see [our Push documentation](https://ably.com/push) for more details | `PushStats` |

</If>

<If lang="objc,swift">

| Property | Description | Type |
|----------|-------------|------|
| unit | The length of the interval that this statistic covers, such as `'minute'`, `'hour'`, `'day'`, `'month'` | `ARTStatsGranularity` |
| intervalGranularity | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions | `ARTStatsGranularity` |
| 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" | `String` |
| all | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| apiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| channels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) |
| connections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) |
| persisted | Messages persisted and later retrieved via the [history API](https://ably.com/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| tokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| push | Detailed stats on push notifications, see [our Push documentation](https://ably.com/push) for more details | `PushStats` |

</If>

<If lang="csharp,ruby">

| Property | Description | Type |
|----------|-------------|------|
| <If lang="swift,ruby">unit</If><If lang="csharp">Unit</If> | The length of the interval that this statistic covers, such as <If lang="ruby">`:minute`, `:hour`, `:day`, `:month`</If><If lang="csharp">`Minute`, `Hour`, `Day`, `Month`</If><If lang="swift">`'minute'`, `'hour'`, `'day'`, `'month'`</If> | <If lang="ruby">[`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)</If><If lang="csharp">[`StatsIntervalGranularity`](https://ably.com/docs/api/realtime-sdk/types#stats-granularity) enum</If><If lang="swift">`ARTStatsGranularity`</If> |
| <If lang="ruby">interval_granularity</If><If lang="swift">intervalGranularity</If><If lang="csharp">IntervalGranularity</If> | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions | <If lang="ruby">[`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)</If><If lang="csharp">[`StatsIntervalGranularity`](https://ably.com/docs/api/realtime-sdk/types#stats-granularity) enum</If><If lang="swift">`ARTStatsGranularity`</If> |
| <If lang="swift">intervalId</If><If lang="ruby">interval_id</If><If lang="csharp">IntervalId</If> | 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" | `String` |
| <If lang="swift,ruby">interval_time</If><If lang="csharp">IntervalTime</If> | A <If lang="ruby">`Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="swift">`Date`</If> object representing the parsed <If lang="swift">`intervalId`</If><If lang="ruby">`interval_id`</If><If lang="csharp">`IntervalId`</If> (the UTC time at which the time period covered by this `Stats` object starts) | <If lang="ruby">`Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="swift">`Date`</If> |
| <If lang="swift,ruby">all</If><If lang="csharp">All</If> | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| <If lang="swift">apiRequests</If><If lang="ruby">api_requests</If><If lang="csharp">ApiRequests</If> | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| <If lang="swift,ruby">channels</If><If lang="csharp">Channels</If> | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) |
| <If lang="swift,ruby">connections</If><If lang="csharp">Connections</If> | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ConnectionTypes) |
| <If lang="swift,ruby">inbound</If><If lang="csharp">Inbound</If> | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) |
| <If lang="swift,ruby">outbound</If><If lang="csharp">Outbound</If> | 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 | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) |
| <If lang="swift,ruby">persisted</If><If lang="csharp">Persisted</If> | Messages persisted and later retrieved via the [history API](https://ably.com/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) |
| <If lang="swift">tokenRequests</If><If lang="ruby">token_requests</If><If lang="csharp">TokenRequests</If> | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) |
| <If lang="swift,ruby">push</If><If lang="csharp">Push</If> | Detailed stats on push notifications, see [our Push documentation](https://ably.com/push) for more details | `PushStats` |

</If>

<If lang="javascript,nodejs">

| Property | Description | Type |
|----------|-------------|------|
| appId | The ID of the Ably application the statistics relate to | `String` |
| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial<Record<String, Number>>` |
| inProgress | Optional. For entries that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` |
| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` |
| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` |

</If>

### <If lang="objc,swift">ARTStatsGranularity</If><If lang="javascript,nodejs,csharp">StatsIntervalGranularity</If> 

<If lang="javascript,nodejs">

`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](https://ably.com/docs/api/rest-sdk/statistics#stats-type).

<If lang="javascript">
<Code>
```javascript
const StatsIntervalGranularity = [
    'minute',
    'hour',
    'day',
    'month'
]
```
</Code>
</If>

<If lang="nodejs">
<Code>
```nodejs
const StatsIntervalGranularity = [
    'minute',
    'hour',
    'day',
    'month'
]
```
</Code>
</If>
</If>

<If lang="swift,objc">

`ARTStatsGranularity` is an enum specifying the granularity of a [`ARTStats interval`](https://ably.com/docs/api/rest-sdk/statistics#stats-type).

<If lang="objc">

<Code>
```objc
typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
    ARTStatsGranularityMinute,
    ARTStatsGranularityHour,
    ARTStatsGranularityDay,
    ARTStatsGranularityMonth
};
```
</Code>

</If>

<If lang="swift">

<Code>

```swift
enum ARTStatsGranularity : UInt {
    case Minute
    case Hour
    case Day
    case Month
}
```

</Code>

</If>

</If>

<If lang="csharp">

`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](https://ably.com/docs/api/rest-sdk/statistics#stats-type).

```csharp
public enum StatsIntervalGranularity
{
    Minute,
    Hour,
    Day,
    Month
}
```

</If>

### HttpPaginatedResponse 

An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](https://ably.com/docs/api/rest-sdk/types#paginated-result), 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](https://ably.com/docs/api/rest-sdk#request).

#### <If lang="javascript,nodejs,swift,objc,flutter,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

<If lang="flutter">

| Property | Description | Type |
|----------|-------------|------|
| statusCode | The HTTP status code of the response | `Number` |
| success | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300` | `Boolean` |
| headers | The headers of the response | `Object` |
| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` |
| errorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

<If lang="java">

| Property | Description | Type |
|----------|-------------|------|
| statusCode | The HTTP status code of the response | `Number` |
| success | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300` | `Boolean` |
| headers | The headers of the response | `Object` |
| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` |
| errorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

<If lang="objc">

| Property | Description | Type |
|----------|-------------|------|
| statusCode | The HTTP status code of the response | `Number` |
| success | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300` | `Boolean` |
| headers | The headers of the response | `Object` |
| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` |
| errorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

<If lang="ruby">

| Property | Description | Type |
|----------|-------------|------|
| status_code | The HTTP status code of the response | `Number` |
| success | Whether the HTTP status code indicates success. This is equivalent to `200 <= status_code < 300` | `Boolean` |
| headers | The headers of the response | `Object` |
| error_code | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` |
| error_message | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

<If lang="swift">

| Property | Description | Type |
|----------|-------------|------|
| statusCode | The HTTP status code of the response | `Number` |
| success | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300` | `Boolean` |
| headers | The headers of the response | `Object` |
| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` |
| errorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

<If lang="javascript,nodejs,csharp">

| Property | Description | Type |
|----------|-------------|------|
| <If lang="javascript,nodejs">statusCode</If><If lang="csharp">StatusCode</If> | The HTTP status code of the response | `Number` |
| <If lang="javascript,nodejs">success</If><If lang="csharp">Success</If> | Whether the HTTP status code indicates success. This is equivalent to <If lang="javascript,nodejs">`200 <= statusCode < 300`</If><If lang="csharp">`200 <= StatusCode < 300`</If> | `Boolean` |
| <If lang="javascript,nodejs">headers</If><If lang="csharp">Headers</If> | The headers of the response | `Object` |
| <If lang="javascript,nodejs">errorCode</If><If lang="csharp">ErrorCode</If> | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | <If lang="javascript,nodejs">`Number`</If><If lang="csharp">`Int`</If> |
| <If lang="javascript,nodejs">errorMessage</If><If lang="csharp">ErrorMessage</If> | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` |

</If>

#### Methods

<If lang="flutter">

##### first

`first(callback(ErrorInfo err, HttpPaginatedResponse resultPage))`

</If>

<If lang="javascript,nodejs">

##### first

`first(): Promise<HttpPaginatedResponse>`

</If>

<If lang="ruby">

##### first

`HttpPaginatedResponse first`

</If>

<If lang="csharp">

##### First

`Task<HttpPaginatedResponse<T>> FirstAsync()`

</If>

<If lang="java">

##### first

`HttpPaginatedResponse first()`

</If>

<If lang="swift,objc">

##### first

`first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)`

</If>

<If lang="csharp,objc,flutter,java,ruby,swift">

Returns a new `HttpPaginatedResponse` for the first page of results. <If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](https://ably.com/docs/api/realtime-sdk/types#http-paginated-response).</If><If lang="csharp">The method is asynchronous and returns a Task which needs to be awaited to get the [`HttpPaginatedResponse`](https://ably.com/docs/api/realtime-sdk/types#http-paginated-response).</If>

</If>

<If lang="nodejs,javascript">

Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.

</If>

##### <If lang="javascript,nodejs,objc,flutter,swift,java">hasNext</If><If lang="csharp">HasNext</If><If lang="ruby">has_next?</If>

<If lang="javascript,nodejs,flutter">

`Boolean hasNext()`

</If>

<If lang="ruby">

`Boolean has_next?`

</If>

<If lang="csharp">

`Boolean HasNext()`

</If>

<If lang="java">

`Boolean hasNext()`

</If>

<If lang="swift,objc">

`Boolean hasNext()`

</If>

<If lang="javascript,nodejs,objc,swift,flutter,java,csharp,ruby">

Returns `true` if there are more pages available by calling <If lang="javascript,nodejs,objc,swift,flutter,java,ruby">`next`</If><If lang="csharp">`Next`</If> and returns `false` if this page is the last page available.

</If>

##### <If lang="javascript,nodejs,objc,swift,flutter,java">isLast</If><If lang="csharp">IsLast</If><If lang="ruby">last?</If>

<If lang="javascript,nodejs,flutter">

`Boolean isLast()`

</If>

<If lang="ruby">

`Boolean last?`

</If>

<If lang="csharp">

`Boolean IsLast()`

</If>

<If lang="java">

`Boolean isLast()`

</If>

<If lang="swift,objc">

`Boolean isLast()`

</If>

<If lang="javascript,nodejs,objc,swift,flutter,java,csharp,ruby">

Returns `true` if this page is the last page and returns `false` if there are more pages available by calling <If lang="javascript,nodejs,java,ruby,flutter,objc,swift">`next`</If><If lang="csharp">`Next`</If> available.

</If>

##### <If lang="javascript,nodejs,java,ruby,flutter,objc,swift">next</If><If lang="csharp">Next</If>

<If lang="flutter">

`next(callback(ErrorInfo err, HttpPaginatedResponse resultPage))`

</If>

<If lang="javascript,nodejs">

`next(): Promise<HttpPaginatedResponse>`

</If>

<If lang="ruby">

`HttpPaginatedResponse next`

</If>

<If lang="csharp">

`Task<HttpPaginatedResponse<T>> NextAsync()`

</If>

<If lang="java">

`HttpPaginatedResponse next()`

</If>

<If lang="swift,objc">

`next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)`

</If>

<If lang="objc,swift,flutter,java,csharp,ruby">

Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then <If lang="flutter,ruby">`null`</If><If lang="csharp">a blank HttpPaginatedResponse will be returned</If><If lang="java">`Null`</If><If lang="objc,swift">`nil`</If> is returned. <If lang="csharp">The method is asynchronous and return a Task which needs to be awaited to get the `HttpPaginatedResponse`</If><If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields an [HttpPaginatedResponse](https://ably.com/docs/api/realtime-sdk/types#http-paginated-response).</If>

</If>

<If lang="javascript,nodejs">

Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null` is returned. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.

##### current

`current(): Promise<HttpPaginatedResponse>`

Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.

</If>

#### Example

The `HttpPaginatedResponse` interface is a superset of `PaginatedResult`, see the [`PaginatedResult` example](https://ably.com/docs/api/rest-sdk/types/#paginated-result-example)

<If lang="java">

### 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`](https://ably.com/docs/api/realtime-sdk/history#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

| Property | Description | Type |
|----------|-------------|------|
| key | The key value | `String` |
| value | The value associated with the `key` | `String` |

</If>

<If lang="javascript,nodejs">

### BatchPublishSpec 

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

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| channels | The names of the channels to publish the `messages` to | `String[]` |
| messages | An array of [`Message`](https://ably.com/docs/api/realtime-sdk/types#message) objects | [`Message[]`](/docs/api/realtime-sdk/types#message) |

### BatchResult 

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

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| successCount | The number of successful operations in the request | `Number` |
| failureCount | The number of unsuccessful operations in the request | `Number` |
| messages | An array of results for the batch operation (for example, an array of [`BatchPublishSuccessResult`](https://ably.com/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](https://ably.com/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` |

### BatchPublishSuccessResult 

A `BatchPublishSuccessResult` contains information about the result of successful publishes to a channel requested by a single [`BatchPublishSpec`](https://ably.com/docs/api/realtime-sdk/types#batch-publish-spec).

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| channel | The name of the channel the message(s) was published to | `String` |
| messageId | A unique ID prefixed to the `Message.id` of each published message | `String` |

### BatchPublishFailureResult 

A `BatchPublishFailureResult` contains information about the result of unsuccessful publishes to a channel requested by a single [`BatchPublishSpec`](https://ably.com/docs/api/realtime-sdk/types#batch-publish-spec).

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| channel | The name of the channel the message(s) failed to be published to | `String` |
| error | Describes the reason for which the message(s) failed to publish to the channel as an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) |

### BatchPresenceSuccessResult 

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

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| channel | The channel name the presence state was retrieved for | `String` |
| presence | An array of [`PresenceMessage`](https://ably.com/docs/api/realtime-sdk/types#presence-message) describing members present on the channel | [`PresenceMessage[]`](/docs/api/realtime-sdk/types#presence-message) |

### BatchPresenceFailureResult 

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

#### Properties

| Property | Description | Type |
|----------|-------------|------|
| channel | The channel name the presence state failed to be retrieved for | `String` |
| error | Describes the reason for which presence state could not be retrieved for the channel as an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) |

</If>