diff --git a/content/api/realtime-sdk/types.textile b/content/api/realtime-sdk/types.textile deleted file mode 100644 index b3f817d4d5..0000000000 --- a/content/api/realtime-sdk/types.textile +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: Types -meta_description: "Realtime Client Library SDK API reference section for types." -meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, types, objects, options" -section: api -index: 60 -languages: - - javascript - - nodejs - - ruby - - java - - swift - - objc - - csharp - - flutter - - go -redirect_from: - - /docs/api/versions/v1.1/realtime-sdk/types - - /docs/api/versions/v1.0/realtime-sdk/types - - /docs/api/versions/v0.8/realtime-sdk/types - - /docs/realtime/types - - /docs/realtime/versions/v1.1/types - - /docs/realtime/versions/v1.0/types - - /docs/realtime/versions/v0.8/types ---- - -The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments. - -Where client libraries support both Realtime and REST APIs, the types are shared between both clients. - -All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object. - -If you are interested in finding out more about the exact types and options definitions in each language, we recommend you download "our open source libraries":https://ably.com/download and review the code. - -h2. Data types - -h3(#ably-exception). - java: io.ably.lib.types.AblyException - ruby: Ably::Exceptions::BaseAblyException - csharp: IO.Ably.AblyException - flutter: ably.AblyException - -blang[java,csharp,flutter]. - <%= partial partial_version('types/_ably_exception'), indent: 2, skip_first_indent: true %> - -blang[ruby]. - <%= partial partial_version('types/_base_ably_exception'), indent: 2, skip_first_indent: true %> - -<%= partial partial_version('types/_channel_details') %> - -blang[jsall,ruby,flutter]. - - h3(#device-details). - jsall: DeviceDetails - ruby: Ably::Models::DeviceDetails - - <%= partial partial_version('types/_device_details'), indent: 2, skip_first_indent: true %> - - h3(#local-device). - jsall: LocalDevice - ruby: Ably::Models::LocalDevice - - <%= partial partial_version('types/_local_device') %> - -h3(#error-info). - default: ErrorInfo - objc,swift: ARTErrorInfo - java: io.ably.lib.types.ErrorInfo - ruby: Ably::Models::ErrorInfo - csharp: IO.Ably.ErrorInfo - flutter: ably.ErrorInfo - -<%= partial partial_version('types/_error_info') %> - -h3(#message). - default: Message - objc,swift: ARTMessage - java: io.ably.lib.types.Message - ruby: Ably::Models::Message - csharp: IO.Ably.Message - -<%= partial partial_version('types/_message') %> - -blang[jsall]. - h3(#message-action). - default: Message action - - <%= partial partial_version('types/_message_action') %> - -h3(#message-annotations). - default: MessageAnnotations - -<%= partial partial_version('types/_message_annotations') %> - -h3(#presence-message). - default: PresenceMessage - objc,swift: ARTPresenceMessage - java: io.ably.lib.types.PresenceMessage - ruby: Ably::Models::PresenceMessage - csharp: IO.Ably.PresenceMessage - -<%= partial partial_version('types/_presence_message') %> - -h3(#presence-action). - default: Presence action - objc,swift: ARTPresenceAction - java: io.ably.lib.types.PresenceMessage.Action - ruby: Ably::Models::PresenceMessage::ACTION - csharp: IO.Ably.PresenceAction - -<%= partial partial_version('types/_presence_action') %> - -h3(#paginated-result). - default: PaginatedResult - objc,swift: ARTPaginatedResult - java: io.ably.lib.types.PaginatedResult - ruby: Ably::Models::PaginatedResult - csharp: IO.Ably.PaginatedResult - -<%= partial partial_version('types/_paginated_result') %> - -h3(#http-paginated-response). - default: HttpPaginatedResponse - -<%= partial partial_version('types/_http_paginated_response') %> - -h3(#param). - java: io.ably.lib.types.Param - -blang[java]. - <%= partial partial_version('types/_param'), indent: 2, skip_first_indent: true %> - -h3(#push-channel-subscription). - jsall: PushChannelSubscription - ruby: Ably::Models::PushChannelSubscription - -blang[jsall,ruby]. - <%= partial partial_version('types/_push_channel_subscription'), indent: 2, skip_first_indent: true %> - -h3(#token-details). - default: TokenDetails - objc,swift: ARTTokenDetails - java: io.ably.lib.types.TokenDetails - ruby: Ably::Models::TokenDetails - csharp: IO.Ably.TokenDetails - -<%= partial partial_version('types/_token_details') %> - -h3(#token-request). - default: TokenRequest - objc,swift: ARTTokenRequest - java: io.ably.lib.types.TokenRequest - ruby: Ably::Models::TokenRequest - csharp: IO.Ably.TokenRequest - flutter: ably.TokenRequest - -<%= partial partial_version('types/_token_request') %> - -h3(#stats). - default: Stats object - objc,swift: ARTStats - java: io.ably.lib.types.Stats - ruby: Ably::Models::Stats - csharp: IO.Ably.Stats - -<%= partial partial_version('types/_stats') %> - -h3(#stats-granularity). - objc,swift: ARTStatsGranularity - jsall: StatsIntervalGranularity - csharp: StatsIntervalGranularity - -<%= partial partial_version('types/_stats_granularity') %> - -blang[jsall]. - - h3(#batch-publish-spec). - jsall: BatchPublishSpec - - <%= partial partial_version('types/_batch_publish_spec') %> - - h3(#batch-result). - jsall: BatchResult - - <%= partial partial_version('types/_batch_result') %> - - h3(#batch-publish-success-result). - jsall: BatchPublishSuccessResult - - <%= partial partial_version('types/_batch_publish_success_result') %> - - h3(#batch-publish-failure-result). - jsall: BatchPublishFailureResult - - <%= partial partial_version('types/_batch_publish_failure_result') %> - - h3(#batch-presence-success-result). - jsall: BatchPresenceSuccessResult - - <%= partial partial_version('types/_batch_presence_success_result') %> - - h3(#batch-presence-failure-result). - jsall: BatchPresenceFailureResult - - <%= partial partial_version('types/_batch_presence_failure_result') %> - - h3(#token-revocation-success-result). - jsall: TokenRevocationSuccessResult - - <%= partial partial_version('types/_token_revocation_success_result') %> - - h3(#token-revocation-failure-result). - jsall: TokenRevocationFailureResult - - <%= partial partial_version('types/_token_revocation_failure_result') %> - -h2. Other types - -h3(#auth-options). - default: AuthOptions Object - objc,swift: ARTAuthOptions - ruby: AuthOptions Hash - java: io.ably.lib.rest.Auth.AuthOptions - csharp: IO.Ably.AuthOptions - -<%= partial partial_version('types/_auth_options') %> - -h3(#client-options). - default: ClientOptions Object - objc,swift: ARTClientOptions - ruby: ClientOptions Hash - java: io.ably.types.ClientOptions - csharp: IO.Ably.ClientOptions - -<%= partial partial_version('types/_realtime_client_options_intro') %> -<%= partial partial_version('types/_client_options') %> -<%= partial partial_version('types/_realtime_client_options') %> - -h3(#channel-options). - default: ChannelOptions Object - objc,swift: ARTChannelOptions - ruby: ChannelOptions Hash - java: io.ably.lib.types.ChannelOptions - csharp: IO.Ably.Rest.ChannelOptions - -<%= partial partial_version('types/_channel_options') %> - -h3(#channel-state). - default: ChannelState - objc,swift: ARTRealtimeChannelState - ruby: Channel::STATE Enum - java: io.ably.lib.realtime.ChannelState Enum - csharp: IO.Ably.Realtime.ChannelState Enum - -<%= partial partial_version('types/_channel_state') %> - -h3(#channel-event). - default: ChannelEvent - swift,objc: ARTChannelEvent - ruby: Channel::EVENT Enum - java: io.ably.lib.realtime.ChannelEvent Enum - csharp: IO.Ably.Realtime.ChannelEvent Enum - -<%= partial partial_version('types/_channel_event') %> - -h3(#channel-state-change). - default: ChannelStateChange Object - objc,swift: ARTRealtimeChannelStateChange - ruby: ChannelStateChange - java: io.ably.lib.realtime.ConnectionStateListener.ChannelStateChange - csharp: IO.Ably.Realtime.ChannelStateChange - -<%= partial partial_version('types/_channel_state_change') %> - -h3(#channel-state-listener). - java: io.ably.lib.realtime.ChannelStateListener - -blang[java]. - <%= partial partial_version('types/_channel_state_listener'), indent: 2, skip_first_indent: true %> - -h3(#cipher-params). - default: CipherParams - objc,swift: ARTCipherParams - ruby: CipherParams Hash - java: io.ably.lib.util.Crypto.CipherParams - csharp: IO.Ably.CipherParams - -<%= partial partial_version('types/_cipher_params') %> - -h3(#completion-listener). - java: io.ably.lib.realtime.CompletionListener - -blang[java]. - <%= partial partial_version('types/_completion_listener'), indent: 2, skip_first_indent: true %> - -h3(#connection-state). - default: ConnectionState - objc,swift: ARTRealtimeConnectionState - ruby: Connection::STATE - java: io.ably.lib.realtime.ConnectionState - csharp: IO.Ably.Realtime.ConnectionState - -<%= partial partial_version('types/_connection_state') %> - -h3(#connection-event). - default: ConnectionEvent - swift,objc: ARTRealtimeConnectionEvent - ruby: Connection::EVENT Enum - java: io.ably.lib.realtime.ConnectionEvent Enum - csharp: IO.Ably.Realtime.ConnectionEvent Enum - -<%= partial partial_version('types/_connection_event') %> - -h3(#connection-state-listener). - java: io.ably.lib.realtime.ConnectionStateListener - -blang[java]. - <%= partial partial_version('types/_connection_state_listener'), indent: 2, skip_first_indent: true %> - -h3(#connection-state-change). - default: ConnectionStateChange Object - objc,swift: ARTConnectionStateChange - ruby: ConnectionStateChange - java: io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange - csharp: IO.Ably.Realtime.ConnectionStateChange - -<%= partial partial_version('types/_connection_state_change') %> - -h3(#paginated-request-params). - csharp: IO.Ably.PaginatedRequestParams - -blang[csharp]. - <%= partial partial_version('types/_history_request_params'), indent: 2, skip_first_indent: true %> - -h3(#message-listener). - java: io.ably.lib.realtime.Channel.MessageListener - -blang[java]. - <%= partial partial_version('types/_message_listener'), indent: 2, skip_first_indent: true %> - -h3(#last-connection-details). - javascript: LastConnectionDetails - -blang[javascript]. - <%= partial partial_version('types/_last_connection_details'), indent: 2, skip_first_indent: true %> - -h3(#presence-listener). - java: io.ably.lib.realtime.Presence.PresenceListener - -blang[java]. - <%= partial partial_version('types/_message_listener'), indent: 2, skip_first_indent: true %> - -blang[ruby]. - h3(#deferrable). - ruby: Ably::Util::SafeDeferrable - - <%= partial partial_version('types/_deferrable'), indent: 2, skip_first_indent: true %> - -h3(#stats-request-params). - csharp: IO.Ably.StatsRequestParams - -blang[csharp]. - <%= partial partial_version('types/_history_request_params'), indent: 2, skip_first_indent: true %> - -h3(#token-params). - default: TokenParams Object - objc,swift: ARTTokenParams - ruby: TokenParams Hash - java: io.ably.lib.rest.Auth.TokenParams - csharp: IO.Ably.TokenParams - -<%= partial partial_version('types/_token_params') %> - -blang[jsall]. - - h3(#token-revocation-target-specifier). - jsall: TokenRevocationTargetSpecifier - - <%= partial partial_version('types/_token_revocation_target_specifier') %> - - h3(#token-revocation-options). - jsall: TokenRevocationOptions - - <%= partial partial_version('types/_token_revocation_options') %> diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx new file mode 100644 index 0000000000..1f50d126d6 --- /dev/null +++ b/src/pages/docs/api/realtime-sdk/types.mdx @@ -0,0 +1,3267 @@ +--- +title: Types +meta_description: "Realtime Client Library SDK API reference section for types." +meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, types, objects, options" +redirect_from: + - /docs/api/versions/v1.1/realtime-sdk/types + - /docs/api/versions/v1.0/realtime-sdk/types + - /docs/api/versions/v0.8/realtime-sdk/types + - /docs/realtime/types + - /docs/realtime/versions/v1.1/types + - /docs/realtime/versions/v1.0/types + - /docs/realtime/versions/v0.8/types +--- + +The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments. + +Where client libraries support both Realtime and REST APIs, the types are shared between both clients. + +All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object. + +If you are interested in finding out more about the exact types and options definitions in each language, we recommend you download [our open source libraries](https://ably.com/download) and review the code. + +## Data types + + + +### io.ably.lib.types.AblyException + + + + +### Ably::Exceptions::BaseAblyException + + + + +### IO.Ably.AblyException + + + + +### ably.AblyException + + + + + +An `AblyException` is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable. + +#### MembersAttributesProperties + +| Property | Description | Type | +|----------|-------------|------| +| errorInfoErrorInfo | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) corresponding to this exception, where applicable | `ErrorInfo` | + + + + + +A `BaseAblyException` is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable. + +#### Attributes + +| Property | Description | Type | +|----------|-------------|------| +| code | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | +| status_code | HTTP Status Code corresponding to this error, where applicable | `Integer` | +| message | Additional message information, where available | `String` | + + + +### ChannelDetails + +`ChannelDetails` is an object returned when requesting or receiving [channel metadata](/docs/metadata-stats/metadata). It contains information on the channel itself, along with the current state of the channel in the [`ChannelStatus`](#channel-status) object. + +| Property | Description | Type | +|----------|-------------|------| +| channelId | The required name of the channel including any qualifier, if any | `string` | +| region | In events relating to the activity of a channel in a specific region, this optionally identifies the region | `string` | +| isGlobalMaster | In events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel | `boolean` | +| status | An optional [`ChannelStatus`](#channel-status) instance | [`ChannelStatus`](#channel-status) | + +The following is an example of a `ChannelDetails` JSON object: + + +```json + { + "channelId": "foo", + "status": { + "isActive": true, + "occupancy": { + "metrics": { + "connections": 1, + "publishers": 1, + "subscribers": 1, + "presenceConnections": 1, + "presenceMembers": 0, + "presenceSubscribers": 1, + "objectPublishers": 1, + "objectSubscribers": 1 + } + } + } + } +``` + + +### ChannelDetails.ChannelStatus + +`ChannelStatus` is contained within the [`ChannelDetails`](#channel-details) object, and optionally contains an [`Occupancy`](#occupancy) object. + +| Property | Description | Type | +|----------|-------------|------| +| isActive | A required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity | `boolean` | +| occupancy | An optional [`Occupancy`](#occupancy) instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity | [`Occupancy`](#occupancy) | + +### ChannelDetails.ChannelStatus.Occupancy + +Occupancy is optionally contained within the [`ChannelStatus`](#channel-status) object, and contains metadata relating to the occupants of the channel. This is usually contained within the `occupancy` attribute of the [`ChannelStatus`](#channel-status) object. + +The `occupancy` attribute contains the `metrics` attribute, which contains the following members: + +| Property | Description | Type | +|----------|-------------|------| +| connections | The number of connections | `integer` | +| publishers | The number of connections attached to the channel that are authorised to publish | `integer` | +| subscribers | The number of connections attached that are authorised to subscribe to messages | `integer` | +| presenceSubscribers | The number of connections that are authorised to subscribe to presence messages | `integer` | +| presenceConnections | The number of connections that are authorised to enter members into the presence channel | `integer` | +| presenceMembers | The number of members currently entered into the presence channel | `integer` | +| objectPublishers | The number of connections that are authorised to publish updates to objects on the channel | `integer` | +| objectSubscribers | The number of connections that are authorised to subscribe to objects on the channel | `integer` | + + + +#### DeviceDetailsAbly::Models::DeviceDetails + +A `DeviceDetails` is a type encapsulating attributes of a device registered for push notifications. + +##### Properties + +| Property | Description | Type | +|----------|-------------|------| +| id | unique identifier for the device generated by the device itself | `String` | +| clientIdclient_id | optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` | +| formFactorform_factor | form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car`, or `embedded` | `String` | +| metadata | optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object` | +| platform | platform of the push device. Must be one of `ios` or `android` | `String` | +| deviceSecret | Secret value for the device | `String` | +| push.recipient | push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api) for more details | `Object` | +| push.state | the current state of the push device being either `Active`, `Failing`, or `Failed` | `String` | +| push.errorReasonpush.error_reason | when the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types) | + +#### LocalDeviceAbly::Models::LocalDevice + +An extension of [`DeviceDetails`](/docs/api/realtime-sdk/types#device-details). In addition to the properties of [`DeviceDetails`](/docs/api/realtime-sdk/types#device-details), it includes the following: + +##### Properties + +| Property | Description | Type | +|----------|-------------|------| +| deviceIdentityToken | a unique identity token for the device | `String` | + + + +### ErrorInfoably.ErrorInfoIO.Ably.ErrorInfoio.ably.lib.types.ErrorInfoARTErrorInfoAbly::Models::ErrorInfo + +An `ErrorInfo` is a type encapsulating error information containing an Ably-specific error code and generic status code. + +#### Properties + + + +| Property | Description | Type | +|----------|-------------|------| +| codeCode | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | +| statusCodestatus_codeStatusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | +| messageMessage | Additional message information, where available | `String` | +| causeCause | Information pertaining to what caused the error where available | `ErrorInfo` | +| hrefHref | Ably may additionally include a URL to get more help on this error | `String` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| code | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | +| statusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | +| message | Additional message information, where available | `String` | +| cause | Information pertaining to what caused the error where available | `ErrorInfo` | +| href | Ably may additionally include a URL to get more help on this error | `String` | +| requestId | Request ID with which the error can be identified | `String` | + + + +#### Error nesting + +ErrorInfo objects can contain nested errors through the `cause` property, allowing you to trace the root cause of failures. When an operation fails due to underlying system errors, the main `ErrorInfo` provides the high-level failure reason while the nested `cause` contains more specific details about what went wrong. + +One example of ErrorInfo nesting is [80019: Auth server rejecting request](/docs/platform/errors/codes#80019) where the main error indicates token renewal failed, while the nested `cause` contains the specific HTTP error from the auth server. + +The following example demonstrates how to handle nested errors: + + + + +```javascript +function handleError(error) { + console.log(`Main error: ${error.code} - ${error.message}`); + + // Check for nested error + if (error.cause) { + console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); + + // Handle further nesting if needed + if (error.cause.cause) { + console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); + } + } +} +``` + + + + + + +```nodejs +function handleError(error) { + console.log(`Main error: ${error.code} - ${error.message}`); + + // Check for nested error + if (error.cause) { + console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); + + // Handle further nesting if needed + if (error.cause.cause) { + console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); + } + } +} +``` + + + + + + +```swift +func handleError(_ error: ARTErrorInfo) { + print("Main error: \(error.code) - \(error.message)") + + if let cause = error.cause { + print("Root cause: \(cause.code) - \(cause.message)") + + if let deeperCause = cause.cause { + print("Deeper cause: \(deeperCause.code) - \(deeperCause.message)") + } + } +} +``` + + + + + + +```objc +- (void)handleError:(ARTErrorInfo *)error { + NSLog(@"Main error: %ld - %@", (long)error.code, error.message); + + if (error.cause) { + NSLog(@"Root cause: %ld - %@", (long)error.cause.code, error.cause.message); + + if (error.cause.cause) { + NSLog(@"Deeper cause: %ld - %@", (long)error.cause.cause.code, error.cause.cause.message); + } + } +} +``` + + + + + + +```flutter +void handleError(ably.ErrorInfo error) { + print('Main error: ${error.code} - ${error.message}'); + + if (error.cause != null) { + print('Root cause: ${error.cause!.code} - ${error.cause!.message}'); + + if (error.cause!.cause != null) { + print('Deeper cause: ${error.cause!.cause!.code} - ${error.cause!.cause!.message}'); + } + } +} +``` + + + + + + +```java +public void handleError(ErrorInfo error) { + System.out.println("Main error: " + error.code + " - " + error.message); + + if (error.cause != null) { + System.out.println("Root cause: " + error.cause.code + " - " + error.cause.message); + + if (error.cause.cause != null) { + System.out.println("Deeper cause: " + error.cause.cause.code + " - " + error.cause.cause.message); + } + } +} +``` + + + + + + +```csharp +void HandleError(ErrorInfo error) +{ + Console.WriteLine($"Main error: {error.Code} - {error.Message}"); + + if (error.Cause != null) + { + Console.WriteLine($"Root cause: {error.Cause.Code} - {error.Cause.Message}"); + + if (error.Cause.Cause != null) + { + Console.WriteLine($"Deeper cause: {error.Cause.Cause.Code} - {error.Cause.Cause.Message}"); + } + } +} +``` + + + + + + +```ruby +def handle_error(error) + puts "Main error: #{error.code} - #{error.message}" + + if error.cause + puts "Root cause: #{error.cause.code} - #{error.cause.message}" + + if error.cause.cause + puts "Deeper cause: #{error.cause.cause.code} - #{error.cause.cause.message}" + end + end +end +``` + + + + + + +```go +func handleError(err *ErrorInfo) { + fmt.Printf("Main error: %d - %s\n", err.Code, err.Message) + + if err.Cause != nil { + fmt.Printf("Root cause: %d - %s\n", err.Cause.Code, err.Cause.Message) + + if err.Cause.Cause != nil { + fmt.Printf("Deeper cause: %d - %s\n", err.Cause.Cause.Code, err.Cause.Cause.Message) + } + } +} +``` + + + + +### Message ARTMessage io.ably.lib.types.Message Ably::Models::Message IO.Ably.Message + +A `Message` represents an individual message that is sent to or received from Ably. + +### nameName + +The event name, if provided.
_Type: `String`_ + +### data Data + +The message payload, if provided. + +_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Map`, `List`_ + +### extras Extras + +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/webhooks#skipping) objects. + +_Type: `JSONObject`, `JSONArray``JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``plain C# object that can be converted to JSON`_ + +### idId + +A Unique ID assigned by Ably to this message.
_Type: `String`_ + +### clientIdClientIdclient_id + +The client ID of the publisher of this message.
_Type: `String`_ + +### connectionIdConnectionIdconnection_id + +The connection ID of the publisher of this message.
_Type: `String`_ + +### connectionKeyConnectionKeyconnection_key + +A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ + +### timestampTimestamp + +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object. + +_Type: `Integer``Long Integer``Time``NSDate``DateTimeOffset``Integer`_ + +### encodingEncoding + +This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ + + + +### action + +The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values. + +_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_ + +### serial + +A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [channel rules](/docs/channels#rules).
_Type: `String`_ + +### annotations + +An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_ + + + +### Message constructors + +#### Message.fromEncoded + +`Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message` + +A static factory method to create a [`Message`](/docs/api/realtime-sdk/types#message) from a deserialized `Message`-like object encoded using Ably's wire protocol. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| encodedMsg | A `Message`-like deserialized object | `Object` | +| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` | + +##### Returns + +A [`Message`](/docs/api/realtime-sdk/types#message) object + +#### Message.fromEncodedArray + +`Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]` + +A static factory method to create an array of [`Messages`](/docs/api/realtime-sdk/types#message) from an array of deserialized `Message`-like object encoded using Ably's wire protocol. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| encodedMsgs | An array of `Message`-like deserialized objects | `Array` | +| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` | + +##### Returns + +An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects + + + +### Message action + +`Message` `action` is a String representing the action type of the message. + + + + +```javascript + const MessageActions = [ + 'message.create', + 'message.update', + 'message.delete', + 'meta', + 'message.summary' + ] +``` + + + + + + +```nodejs + const MessageActions = [ + 'message.create', + 'message.update', + 'message.delete', + 'meta', + 'message.summary' + ] +``` + + + + + +### MessageAnnotations + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| summary | An object whose keys are annotation types, and the values are aggregated summaries for that annotation type | `Record` | + +### PresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageARTPresenceMessageIO.Ably.PresenceMessage + +A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. + +#### PropertiesMembers + +| Property | Description | Type | +|----------|-------------|------| +| actionAction | The event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[Presence action](/docs/api/realtime-sdk/types#presence-action)[`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction``enum { Absent, Present, Enter, Leave, Update }``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `StringBuffer`, `JSON Object``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Map`, `List` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/channels/messages#interactions) and [`privileged`](/docs/platform/integrations/webhooks#skipping) objects | `JSONObject`, `JSONArray``JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *`plain C# object that can be converted to Json`String`, `[]byte``Map`, `List` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | + +### PresenceMessage constructors + +#### PresenceMessage.fromEncoded + +`PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) -> PresenceMessage` + +A static factory method to create a [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) from a deserialized `PresenceMessage`-like object encoded using Ably's wire protocol. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| encodedPresMsg | A `PresenceMessage`-like deserialized object | `Object` | +| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` | + +##### Returns + +A [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) object + +#### PresenceMessage.fromEncodedArray + +`PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) -> PresenceMessage[]` + +A static factory method to create an array of [`PresenceMessages`](/docs/api/realtime-sdk/types#presence-message) from an array of deserialized `PresenceMessage`-like object encoded using Ably's wire protocol. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| encodedPresMsgs | An array of `PresenceMessage`-like deserialized objects | `Array` | +| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` | + +##### Returns + +An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects + +### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction + + + +`Presence` `action` is a String with a value matching any of the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). + + + + +```javascript + var PresenceActions = [ + 'absent', // (reserved for internal use) + 'present', + 'enter', + 'leave', + 'update' + ] +``` + + + + + + +```nodejs + var PresenceActions = [ + 'absent', // (reserved for internal use) + 'present', + 'enter', + 'leave', + 'update' + ] +``` + + + + + + +```go +const ( + PresenceAbsent = 0 + PresencePresent = 1 + PresenceEnter = 2 + PresenceLeave = 3 + PresenceUpdate = 4 +) +``` + + + + + + +`io.ably.lib.types.PresenceMessage.Action` is an enum representing all the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). + + +```java + public enum Action { + ABSENT, // 0 (reserved for internal use) + PRESENT, // 1 + ENTER, // 2 + LEAVE, // 3 + UPDATE // 4 + } +``` + + + + + +`IO.Ably.PresenceAction` is an enum representing all the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). + + +```csharp + public enum Action { + Absent, // 0 (reserved for internal use) + Present, // 1 + Enter, // 2 + Leave, // 3 + Update // 4 + } +``` + + + + + +`Ably::Models::PresenceMessage::ACTION` is an enum-like value representing all the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). `ACTION` can be represented interchangeably as either symbols or constants. + +#### Symbol states + + +```ruby + :absent # => 0 (reserved for internal use) + :present # => 1 + :enter # => 2 + :leave # => 3 + :update # => 4 +``` + + +#### Constant states + + +```ruby + PresenceMessage::ACTION.Absent # => 0 (internal use) + PresenceMessage::ACTION.Present # => 1 + PresenceMessage::ACTION.Enter # => 2 + PresenceMessage::ACTION.Leave # => 3 + PresenceMessage::ACTION.Update # => 4 +``` + + +#### Example usage + + +```ruby + # Example with symbols + presence.on(:attached) { ... } + + # Example with constants + presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... } + + # Interchangeable + Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true +``` + + + + + +`ARTPresenceAction` is an enum representing all the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). + + + + +```objc + typedef NS_ENUM(NSUInteger, ARTPresenceAction) { + ARTPresenceAbsent, // reserved for internal use + ARTPresencePresent, + ARTPresenceEnter, + ARTPresenceLeave, + ARTPresenceUpdate + }; +``` + + + + + + +```swift + enum ARTPresenceAction : UInt { + case Absent // reserved for internal use + case Present + case Enter + case Leave + case Update + } +``` + + + + + +`Presence` `action` is a String with a value matching any of the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). + + +```go +const ( + PresenceAbsent = 0 + PresencePresent = 1 + PresenceEnter = 2 + PresenceLeave = 3 + PresenceUpdate = 4 +) +``` + + + + + + +### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResultIO.Ably.PaginatedResult + +A `PaginatedResult` is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a [Ably REST API paginated query](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| itemsItems | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | + +#### Methods + +##### firstFirst + + + +`first(): Promise` + + + + +`PaginatedResult first` + + + + +`Task> FirstAsync()` + + + + +`PaginatedResult first()` + + + + +`first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)` + + + + +`First() (PaginatedResult, error)` + + + + + +Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [`PaginatedResult`](#paginated-result). + + + + +Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + +##### hasNextHasNexthas_next? + + + +`Boolean hasNext()` + + + + +`Boolean has_next?` + + + + +`Boolean HasNext()` + + + + +`HasNext() (bool)` + + + +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. + +##### isLastIsLastlast? + + + +`Boolean isLast()` + + + + +`Boolean last?` + + + + +`Boolean IsLast()` + + + + +`IsLast() (bool)` + + + +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. + +##### nextNext + + + +`next(): Promise` + + + + +`PaginatedResult next` + + + + +`Task> NextAsync()` + + + + +`PaginatedResult next()` + + + + +`next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)` + + + + +`Next() (PaginatedResult, error)` + + + + + +Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null`a blank PaginatedResult will be returned`nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result). + + + + + +Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + +##### current + +`current(): Promise<"PaginatedResult":#paginated-result>` + +Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` loaded with the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + +#### Example + + + + + + +```javascript +const paginatedResult = await channel.history(); +console.log('Page 0 item 0:' + paginatedResult.items[0].data); +const nextPage = await paginatedResult.next(); +console.log('Page 1 item 1: ' + nextPage.items[1].data); +console.log('Last page?: ' + nextPage.isLast()); +``` + + + + + + +```nodejs +const paginatedResult = await channel.history(); +console.log('Page 0 item 0:' + paginatedResult.items[0].data); +const nextPage = await paginatedResult.next(); +console.log('Page 1 item 1: ' + nextPage.items[1].data); +console.log('Last page?: ' + nextPage.isLast()); +``` + + + + + + + + + +```java +PaginatedResult firstPage = channel.history(); +System.out.println("Page 0 item 0:" + firstPage.items[0].data); +if (firstPage.hasNext) { + PaginatedResult nextPage = firstPage.next(); + System.out.println("Page 1 item 1:" + nextPage.items[1].data); + System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext())); +}; +``` + + + + + + + +```csharp +PaginatedResult firstPage = await channel.HistoryAsync(null); +Message firstMessage = firstPage.Items[0]; +Console.WriteLine("Page 0 item 0: " + firstMessage.data); +if (firstPage.HasNext) +{ + var nextPage = await firstPage.NextAsync(); + Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data); + Console.WriteLine("More pages?: " + nextPage.HasNext()); +} +``` + + + + + + +```ruby +# When using the REST sync library +first_page = channel.history +puts "Page 0 item 0: #{first_page.items[0].data}" +if first_page.has_next? + next_page = first_page.next + puts "Page 1 item 1: #{next_page.items[1].data}" + puts "Last page?: #{next_page.is_last?}" +end + +# When using the Realtime EventMachine library +channel.history do |first_page| + puts "Page 0 item 0: #{first_page.items[0].data}" + if first_page.has_next? + first_page.next do |next_page| + puts "Page 1 item 1: #{next_page.items[1].data}" + puts "Last page?: #{next_page.is_last?}" + end + end +end +``` + + + + + + +```objc +[channel history:^(ARTPaginatedResult *paginatedResult, ARTErrorInfo *error) { + NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data); + [paginatedResult next:^(ARTPaginatedResult *nextPage, ARTErrorInfo *error) { + NSLog(@"Page 1 item 1: %@", nextPage.items[1].data); + NSLog(@"Last page?: %d", nextPage.isLast()); + }]; +}]; +``` + + + + + + +```swift +channel.history { paginatedResult, error in + guard let paginatedResult = paginatedResult else { + print("No results available") + return + } + print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)") + paginatedResult.next { nextPage, error in + guard let nextPage = nextPage else { + print("No next page available") + return + } + print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)") + print("Last page? \(nextPage.isLast())") + } +} +``` + + + + + + +```go + page0, err := channel.History(nil) + fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data) + page1, err := page0.Next() + fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data) + fmt.Println("Last page? %s\n", page1.IsLast()) +``` + + + + +### HttpPaginatedResponse + +An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/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](/docs/api/rest-sdk#request). + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| itemsItems | Contains a page of results; for example, an array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request | `Array<>` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int``Number` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | + + +#### Methods + +##### firstFirst + + + +`first(): Promise` + + + + +`HttpPaginatedResponse first` + + + + +`Task> FirstAsync()` + + + + +`HttpPaginatedResponse first()` + + + + +`first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)` + + + + +`First() (HttpPaginatedResponse, error)` + + + + + +Returns a new `HttpPaginatedResponse` for the first page of results. When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response).The method is asynchronous and returns a Task which needs to be awaited to get the [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response). + + + + +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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + +##### hasNextHasNexthas_next? + + + +`Boolean hasNext()` + + + + +`Boolean has_next?` + + + + +`Boolean HasNext()` + + + + +`HasNext() (bool)` + + + +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. + +##### isLastIsLastlast? + + + +`Boolean isLast()` + + + + +`Boolean last?` + + + + +`Boolean IsLast()` + + + + +`IsLast() (bool)` + + + +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. + +##### nextNext + + + +`next(): Promise` + + + + +`HttpPaginatedResponse next` + + + + +`Task> NextAsync()` + + + + +`HttpPaginatedResponse next()` + + + + +`next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)` + + + + +`Next() (HttpPaginatedResponse, error)` + + + + + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null`a blank HttpPaginatedResponse will be returned`nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `HttpPaginatedResponse`When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response). + + + + +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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + + + +##### current + +`current(): Promise` + +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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + +#### Example + +The `HttpPaginatedResponse` interface is a superset of `PaginatedResult`, see the [`PaginatedResult` example](/docs/api/rest-sdk/types/#paginated-result-example) + + + +### io.ably.lib.types.Param + +`Param` is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see [`Channel#history`](/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` | + + + + + +### PushChannelSubscriptionAbly::Models::PushChannelSubscription + +An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channel | The channel that this push notification subscription is associated with | `String` | +| deviceIddevice_id | The device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | `String` | +| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | `String` | + + + + + +### PushChannelSubscription constructors + +#### PushChannelSubscription.forDevice + + + +`PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription` + + + + +`PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription` + + + +A static factory method to create a `PushChannelSubscription` object for a channel and single device. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| channel | Channel name linked to this push channel subscription | `String` | +| deviceIddevice_id | The device with this identifier will be linked with this push channel subscription | `String` | + +##### Returns + +A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscription) object + +#### PushChannelSubscription.forClient + + + +`PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription` + + + + +`PushChannelSubscription.for_client(String channel, String client_id) -> PushChannelSubscription` + + + +A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/auth/identified-clients). + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| channel | Channel name linked to this push channel subscription | `String` | +| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` | + +##### Returns + +A `PushChannelSubscription` object + + + +### TokenDetailsio.ably.lib.types.TokenDetailsARTTokenDetailsAbly::Models::TokenDetails + +`TokenDetails` is a type providing details of Ably Token string and its associated metadata. + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | +| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | +| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | + + + +### Methods + +| Method | Description | Type | +|--------|-------------|------| +| expired? | True when the token has expired | `Boolean` | + + + + +### Methods + +| Method | Description | Type | +|--------|-------------|------| +| IsValidToken() | True if the token has not expired | `Boolean` | + + + +### TokenDetails constructors + +#### TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap + + + +`TokenDetails.fromJson(String json) -> TokenDetails` + + + + +`TokenDetails.from_json(String json) -> TokenDetails` + + + + +`TokenDetails.fromMap(Map map)` + + + +A static factory methodnamed constructor to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) from a deserialized `TokenDetails`-like object or a JSON stringified `TokenDetails`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenDetails` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenDetails`, Ably ensures that all fields are consistently serialized and deserialized across platforms. + +##### Parameters + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| json | A `TokenDetails`-like deserialized object or JSON stringified `TokenDetails` | `Object, String` | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| map | A `TokenDetails`-like deserialized map | `Map` | + + + +##### Returns + +A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object + +### TokenRequestIO.Ably.TokenRequestably.TokenRequestio.ably.lib.types.TokenRequestARTTokenRequestAbly::Models::TokenRequest + +`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [`Auth#requestToken`](/docs/api/rest-sdk/authentication#request-token)[`Auth#request_token`](/docs/api/rest-sdk/authentication#request-token) + + + +#### Properties + + + + +#### Members + + + + +#### Attributes + + + +| Property | Description | Type | +|----------|-------------|------| +| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | +| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval` | +| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``Integer` | +| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | +| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | +| nonceNonce | An opaque nonce string of at least 16 characters | `String` | +| macMac | The Message Authentication Code for this request | `String` | + +### TokenRequest constructors + +#### TokenRequest.fromJsonTokenRequest.fromMap + + + +`TokenRequest.fromJson(String json) -> TokenRequest` + + + + +`TokenRequest.from_json(String json) -> TokenRequest` + + + + +`TokenRequest.fromMap(Map map)` + + + +A static factory methodnamed constructor to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) from a deserialized `TokenRequest`-like object or a JSON stringified `TokenRequest`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenRequest` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenRequest`, Ably ensures that all fields are consistently serialized and deserialized across platforms. + +##### Parameters + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| json | A `TokenRequest`-like deserialized object or JSON stringified `TokenRequest` | `Object, String` | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| map | A `TokenRequest`-like deserialized map | `Map` | + + + +##### Returns + +A [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object + +### Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.stats + +A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). + + + +Please note that most attributes of the `Stats` type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the [Ruby library stats documentation](https://www.rubydoc.info/gems/ably/Ably/Models/Stats) which contains exhaustive stats documentation. Ruby uses `under_score` case instead of the default `camelCase` in most languages, so please bear that in mind. + + + + + +#### Properties + + + + +#### Members + + + + +#### Attributes + + + + + +| Property | Description | Type | +|----------|-------------|------| +| unitunit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'` | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| interval_granularityintervalGranularity | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `minute`, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | 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) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | Statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/push) for more details | `PushStats` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| unitunit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'` | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| interval_granularityintervalGranularity | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `minute`, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| interval_timeIntervalTime | A `Time``DateTimeOffset` object representing the parsed interval_idIntervalId (the UTC time at which the time period covered by this `Stats` object starts) | `Time``DateTimeOffset` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | 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) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | Statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/push) for more details | `PushStats` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| unitunit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'` | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `minute`, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | 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) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | Statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/push) for more details | `PushStats` | + + + + + +| 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>` | +| 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` | + + + +{/* - xchgProducer/xchg_producer/XchgProducer := Breakdown of messages have been sent or received through any Data Stream Exchange products associated with this app or account - Type: @XchgMessages@ */} +{/* - xchgConsumer/xchg_consumer/XchgConsumer := Breakdown of messages have been sent or received by this app or account connecting to some Data Stream Exchange product as a consumer - Type: @XchgMessages@ */} + + + +### StatsIntervalGranularityARTStatsGranularity + + + +`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](/docs/api/rest-sdk/statistics#stats-type). + + + + +```javascript +const StatsIntervalGranularity = [ + 'minute', + 'hour', + 'day', + 'month' +] +``` + + + + + + +```nodejs +const StatsIntervalGranularity = [ + 'minute', + 'hour', + 'day', + 'month' +] +``` + + + + + + + +`ARTStatsGranularity` is an enum specifying the granularity of a [`ARTStats interval`](/docs/api/rest-sdk/statistics#stats-type). + + + +```objc +typedef NS_ENUM(NSUInteger, ARTStatsGranularity) { + ARTStatsGranularityMinute, + ARTStatsGranularityHour, + ARTStatsGranularityDay, + ARTStatsGranularityMonth +}; +``` + + + + + +```swift +enum ARTStatsGranularity : UInt { + case Minute + case Hour + case Day + case Month +} +``` + + + + + + + +`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](/docs/api/rest-sdk/statistics#stats-type). + +```csharp +public enum StatsIntervalGranularity +{ + Minute, + Hour, + Day, + Month +} +``` + + + + + +### 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`](/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`](/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](/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`](/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`](/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`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/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`](/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`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | + +### TokenRevocationSuccessResult + +A `TokenRevocationSuccessResult` contains information about the result of a successful token revocation request for a single target specifier. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| target | The target specifier | `String` | +| appliesAt | The time at which the token revocation will take effect, as a Unix timestamp in milliseconds | `Number` | +| issuedBefore | A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked | `Number` | + +### TokenRevocationFailureResult + +A `TokenRevocationFailureResult` contains information about the result of an unsuccessful token revocation request for a single target specifier. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| target | The target specifier | `String` | +| error | Describes the reason for which token revocation failed for the given `target` as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | + + + +## Other types + +### AuthOptions ObjectARTAuthOptionsAuthOptions Hashio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions + + + +`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/auth) requests. If passed in, an `authOptions` object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported: + + + + + +`AuthOptions` is a Hash object and is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash: + + + + + +`ART``AuthOptions` is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated. + + + + + +#### Properties + + + + +#### Members + + + + +#### Attributes + + + +| Property | Description | Type | +|----------|-------------|------| +| authCallbackAuthCallback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instanceproc / 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>` | +| authUrlAuthUrl: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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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. | `String``Uri``NSURL``String` | +| authMethodAuthMethod:auth_method | _`GET``:get`_ The HTTP verb to use for the request, either `GET``:get` or `POST``:post` | `String``Symbol``HttpMethod` | +| authHeadersAuthHeaders:auth_headers | A set of key value pair headers to be added to any request made to the authUrlAuthUrl:auth_url. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Hash``Param[]``Dictionary``Map` | +| authParamsAuthParams:auth_params | A set of key value pair params to be added to any request made to the authUrlAuthUrl:auth_url. When the authMethodAuthMethod:auth_method is `GET`, query params are added to the URL, whereas when authMethodAuthMethod: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. | `Object``Hash``Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetails:token_details | An authenticated [`TokenDetails`](/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 authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| keyKey:key | Optionally the [API key](/docs/auth#api-key) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | +| queryTimeQueryTime:query_time | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/docs/auth/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. | `Boolean` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the tokenToken:token property of a [`TokenDetails`](/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](/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 authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | + +### ClientOptions ObjectARTClientOptionsClientOptions Hashio.ably.types.ClientOptionsIO.Ably.ClientOptions + + + +`ClientOptions` is a plain JavaScript object and is used in the `Ably.Realtime` constructor's `options` argument. The following attributes can be defined on the object: + + + + + +`ClientOptions` is a Hash object and is used in the `Ably::Realtime` constructor's `options` argument. The following key symbol values can be added to the Hash: + + + + + +`ART``ClientOptions` is used in the `AblyRealtime` constructor's `options` argument. + + + + +#### Properties + + + + +#### Members + + + + +#### Attributes + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `String` | +| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | +| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request | `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 | `Object` | +| tokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` | +| useBinaryProtocol | 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 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)
**Default:** falsetrue | `Boolean` | +| 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
**Default:** true | `Boolean` | +| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| 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) | `Integer` | +| logHandler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used
**Default:** `console.log` | `Callable` | +| transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet` | `String[]` | +| recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for further informationThis 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`](/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](/docs/connect/states) for further information and example code | `String`, `Callable``String` | +| closeOnUnload | 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`](/docs/api/realtime-sdk/connection#close) method of the [`Connection object`](/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
**Default:** true | `Boolean` | +| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| defaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `Integer` | +| 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
**Default:** 30,000ms | `Integer` | +| pushServiceWorkerUrl | A URL pointing to a service worker script which is used as the target for web push notifications | `String` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| Token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `Token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `Func>` | +| 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `Uri` | +| AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `HttpMethod` | +| 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 | `Dictionary` | +| 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 | `Dictionary` | +| TokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| TransportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Dictionary` | +| 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
**Default:** `Error` | `Enum` | +| 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
**Default:** `IO.Ably.DefaultLoggerSink` | `ILoggerSink` | +| 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)
**Default:** true | `Boolean` | +| 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
**Default:** true | `Boolean` | +| EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| Recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/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](/docs/connect/states) for further information and example code | `String` | +| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| DefaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `Integer` | +| 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
**Default:** 30,000ms | `Integer` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `String` | +| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | +| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `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 | `Param[]` | +| tokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** Null | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** Null | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `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
**Default:** 5 | `Integer` | +| 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
**Default:** `System.out PrintStream` | `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)
**Default:** true | `Boolean` | +| 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
**Default:** true | `Boolean` | +| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/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](/docs/connect/states) for further information and example code | `String` | +| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| defaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `Integer` | +| 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
**Default:** 30,000ms | `Integer` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| :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](/docs/auth/basic) | `String` | +| :token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the :token property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `String` | +| :auth_method | The HTTP verb to use for the request, either `:get` or `:post`
**Default:** `:get` | `Symbol` | +| :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 | `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 | `Hash` | +| :token_details | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| :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](/docs/auth/identified-clients) | `String` | +| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| :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](/docs/platform/account/enterprise-customization) for more details
**Default:** nil | `String` | +| :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](/docs/platform/account/enterprise-customization) for more details
**Default:** nil | `String` | +| :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
**Default:** false | `Boolean` | +| :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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| :transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `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
**Default:** `:error` | `Symbol`, [`Logger::SEVERITY`](http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description) | +| :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
**Default:** `STDOUT Logger` | [Ruby `Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) | +| :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)
**Default:** true | `Boolean` | +| :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
**Default:** true | `Boolean` | +| :echo_messages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| :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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| :recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recovery_key`](/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](/docs/connect/states) for further information and example code | `String` | +| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| :default_token_params | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15s | `Integer` | +| :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
**Default:** 30s | `Integer` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `NSURL` | +| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | +| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `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 | `[NSURLQueryItem]/Array` | +| tokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** nil | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** nil | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` | +| logLevel | An enum controlling the verbosity of the output from `ARTLogLevelVerbose` to `ARTLogLevelNone`. A special value of 99 will silence all logging
**Default:** `ARTLogLevelWarn` | `ARTLogLevel` | +| logHandler | A `ARTLog` object can be specified to handle each line of log output. If `logHandler` is not specified, a default `ARTLog` instance is used
**Default:** default `ARTLog` instance | `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)
**Default:** true | `Boolean` | +| logExceptionReportingUrl | Defaults to a string value for an Ably error reporting Data Source Name | `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
**Default:** true | `Boolean` | +| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/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](/docs/connect/states) for further information and example code | `String` | +| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| defaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `NSTimeInterval` | +| 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
**Default:** 30,000ms | `NSTimeInterval` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `String` | +| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | +| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Map` | +| 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 | `Map` | +| tokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Map` | +| 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)
**Default:** true | `Boolean` | +| 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
**Default:** true | `Boolean` | +| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| defaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `Integer` | +| 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
**Default:** 30,000ms | `Integer` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| 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](/docs/auth/basic) | `String` | +| Token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/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](/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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/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 | `String` | +| AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | +| AuthHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Map` | +| 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 | `Map` | +| TokenDetails | An authenticated [`TokenDetails`](/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](/docs/auth/token) | `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)
**Default:** true | `Boolean` | +| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | +| 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
**Default:** false | `Boolean` | +| 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
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | +| TransportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Map` | +| 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)
**Default:** true | `Boolean` | +| 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
**Default:** true | `Boolean` | +| EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | +| 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`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | +| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/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](/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
**Default:** false | `Boolean` | +| DefaultTokenParams | When a [TokenParams](/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 | [`TokenParams`](/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
**Default:** 15,000ms | `Integer` | +| 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
**Default:** 30,000ms | `Integer` | + + + +### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelOptionsIO.Ably.Rest.ChannelOptions + +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). + + + +`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: + + + + + +`ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash: + + + + + +`ART``io.ably.lib.types.``ChannelOptions` may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. + + + + + +`IO.Ably.ChannelOptions` may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. + + + + + +#### Properties + + + + +#### Members + + + + +#### Attributes + + + + + +| Property | Description | Type | +|----------|-------------|------| +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map``JSON Object` | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| :cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption) | [CipherParams](/docs/api/realtime-sdk/encryption) or an options hash containing at a minimum a `key` | + + + + + +| Property | Description | Type | +|----------|-------------|------| +| CipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption) | [CipherParams](/docs/api/realtime-sdk/encryption) | + + + + + +Request encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption)
Type: [CipherParams](/docs/api/realtime-sdk/encryption) + + + + + +#### Static methods + +##### withCipherKey + +`static ChannelOptions.withCipherKey(Byte[] or String key)` + +A helper method to generate a `ChannelOptions` for the simple case where you only specify a key. + +##### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| key | A binary `Byte[]` array or a base64-encoded `String`. | `Byte[]` or `String` | + +##### Returns + +On success, the method returns a complete `ChannelOptions` object. Failure will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + + + +### ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enum + + + +`ChannelState` is a String with a value matching any of the [Realtime Channel states](/docs/channels/states). + + +```javascript +var ChannelStates = [ + 'initialized', + 'attaching', + 'attached', + 'detaching', + 'detached', + 'failed', + 'suspended' +] +``` + + + + + + +`io.ably.lib.realtime.ChannelState` is an enum representing all the [Realtime Channel states](/docs/channels/states). + + +```java +public enum ChannelState { + initialized, // 0 + attaching, // 1 + attached, // 2 + detaching, // 3 + detached, // 4 + failed // 5 +} +``` + + + + + + +`IO.Ably.Realtime.ChannelState` is an enum representing all the [Realtime Channel states](/docs/channels/states). + + +```csharp +public enum ChannelState +{ + Initialized = 0, + Attaching = 1, + Attached = 2, + Detaching= 3, + Detached = 4, + Failed = 5 +}; +``` + + + + + + +`Ably::Realtime::Channel::STATE` is an enum-like value representing all the [Realtime Channel states](/docs/channels/states). `STATE` can be represented interchangeably as either symbols or constants. + +#### Symbol states + + +```ruby +:initialized # => 0 +:attaching # => 1 +:attached # => 2 +:detaching # => 3 +:detached # => 4 +:failed # => 5 +``` + + +#### Constant states + + +```ruby +Channel::STATE.Initialized # => 0 +Channel::STATE.Attaching # => 1 +Channel::STATE.Attached # => 2 +Channel::STATE.Detaching # => 3 +Channel::STATE.Detached # => 4 +Channel::STATE.Failed # => 5 +``` + + +#### Example usage + + +```ruby +# Example with symbols +channel.on(:attached) { ... } + +# Example with constants +channel.on(Ably::Realtime::Channel::STATE.Attached) { ... } + +# Interchangeable +Ably::Realtime::Channel::STATE.Attached == :attached # => true +``` + + + + + + +`ARTRealtimeChannelState` is an enum representing all the [Realtime Channel states](/docs/channels/states). + + + + +```objc +typedef NS_ENUM(NSUInteger, ARTRealtimeChannelState) { + ARTRealtimeChannelInitialized, + ARTRealtimeChannelAttaching, + ARTRealtimeChannelAttached, + ARTRealtimeChannelDetaching, + ARTRealtimeChannelDetached, + ARTRealtimeChannelFailed +}; +``` + + + + + + +```swift +public enum ARTRealtimeChannelState : UInt { + case Initialized + case Attaching + case Attached + case Detaching + case Detached + case Failed +} +``` + + + + + + + +`ChannelState` is a string representing all the [channel states](/docs/channels/states) + + +```go +const ( + StateChanInitialized = 256 + StateChanConnecting = 512 + StateChanConnected = 1024 + StateChanDisconnected = 2048 + StateChanSuspended = 4096 + StateChanClosing = 8192 + StateChanClosed = 16384 + StateChanFailed = 32768 +) +``` + + + + + + +`ably.ChannelState` is an enum representing all the [Realtime Channel states](/docs/channels/states). + + +```flutter +enum ChannelState { + initialized, + attaching, + attached, + detaching, + detached, + suspended, + failed +} +``` + + + + +### ChannelEventARTChannelEventChannel::EVENT Enumio.ably.lib.realtime.ChannelEvent EnumIO.Ably.Realtime.ChannelEvent Enum + + + +`ChannelEvent` is a String that can be emitted as an event on the `Channel` object; either a [ChannelState](/docs/channels/states) or an `update` event. + + +```javascript +var ChannelEvents = [ + 'initialized', + 'attaching', + 'attached', + 'detaching', + 'detached', + 'failed', + 'suspended', + 'update' +] +``` + + + + + + +`io.ably.lib.realtime.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](/docs/channels/states) or an `update` event. + + +```java +public enum ChannelEvent { + initialized, // 0 + attaching, // 1 + attached, // 2 + detaching, // 3 + detached, // 4 + failed // 5 + update // 6 +} +``` + + + + + + +`IO.Ably.Realtime.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](/docs/channels/states) or an `Update` event. + + +```csharp +public enum ChannelEvent +{ + Initialized = 0, + Attaching = 1, + Attached = 2, + Detaching= 3, + Detached = 4, + Failed = 5, + Update = 6 +}; +``` + + + + + + +`Ably::Realtime::Channel::EVENT` is an enum-like value representing all the events that can be emitted be the `Channel`; either a [ChannelState](/docs/channels/states) or an `:update` event. `EVENT` can be represented interchangeably as either symbols or constants. + +#### Symbol states + + +```ruby +:initialized # => 0 +:attaching # => 1 +:attached # => 2 +:detaching # => 3 +:detached # => 4 +:failed # => 5 +:update # => 6 +``` + + +#### Constant states + + +```ruby +Channel::EVENT.Initialized # => 0 +Channel::EVENT.Attaching # => 1 +Channel::EVENT.Attached # => 2 +Channel::EVENT.Detaching # => 3 +Channel::EVENT.Detached # => 4 +Channel::EVENT.Failed # => 5 +Channel::EVENT.Update # => 6 +``` + + + + + + +`ARTChannelEvent` is the enum emitted as the event in `ARTRealtimeChannel.on`; either a [ChannelState](/docs/api/realtime-sdk/channels#channel-state) or an `Update` event. + + + + +```objc +typedef NS_ENUM(NSUInteger, ARTChannelEvent) { + ARTChannelEventInitialized, + ARTChannelEventAttaching, + ARTChannelEventAttached, + ARTChannelEventDetaching, + ARTChannelEventDetached, + ARTChannelEventFailed, + ARTChannelEventUpdate +}; +``` + + + + + + +```swift +enum ARTChannelEvent : UInt { + case Initialized + case Attaching + case Attached + case Detaching + case Detached + case Failed + case Update +} +``` + + + + + + + +`ChannelEvent` is a String that can be emitted as an event on the `Channel` object; either a [ChannelState](/docs/channels/states) or an `update` event. + + +```go +const ( + StateChanInitialized = 256 + StateChanConnecting = 512 + StateChanConnected = 1024 + StateChanDisconnected = 2048 + StateChanSuspended = 4096 + StateChanClosing = 8192 + StateChanClosed = 16384 + StateChanFailed = 32768 +) +``` + + + + + + +`ably.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](/docs/channels/states) or an `update` event. + + +```flutter +enum ChannelEvent { + initialized, + attaching, + attached, + detaching, + detached, + suspended, + failed, + update +} +``` + + + + +### ChannelStateChange ObjectARTRealtimeChannelStateChangeChannelStateChangeio.ably.lib.realtime.ConnectionStateListener.ChannelStateChangeIO.Ably.Realtime.ChannelStateChange + +A `Ably::Models::ChannelStateChange``ChannelStateChange``ARTRealtimeChannelStateChange` is a type encapsulating state change information emitted by the [Channel](/docs/channels) object. See [Channel#on](/docs/api/realtime-sdk/channels#on) to register a listener for one or more events. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| currentCurrent | The new current state | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | +| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | +| eventEvent | The event that triggered this state change | [`ChannelEvent`](/docs/api/realtime-sdk/types#channel-event)[`Channel::EVENT`](/docs/api/realtime-sdk/types#channel-event) | +| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| resumedResumed | A boolean indicated whether message continuity on this channel is preserved, see [Nonfatal channel errors](/docs/channels#non-fatal-errors) for more info. | `Boolean` | + + + +### io.ably.lib.realtime.ChannelStateListener + +A `io.ably.lib.realtime.ChannelStateListener` is an interface allowing a client to be notified of [channel state changes](/docs/api/realtime-sdk/types#channel-state-change) for a [Channel](/docs/channels) + + +```java +public interface ChannelStateListener { + // Called when the channel state changes + public void onChannelStateChanged(ChannelStateChange stateChange, ErrorInfo reason); +} +``` + + + + +### CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams + +A `CipherParams` contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. + +Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). + +#### PropertiesMembers + + + +| Property | Description | Type | +|----------|-------------|------| +| keyKey:key | A binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | Binary or `String` | +| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| mode:modeMode | _CBC_ The cipher mode | `String``CipherMode` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| algorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| keyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| mode | _CBC_ The cipher mode | `String` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| modeMode | _CBC_ The cipher mode | `String``CipherMode` | +| keySpec | A `KeySpec` for the cipher key | `SecretKeySpec` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| Algorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| KeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| Mode | _CBC_ The cipher mode | `String` | + + + + + +### io.ably.lib.realtime.CompletionListener + +A `io.ably.lib.realtime.CompletionListener` is an interface allowing a client to be notified of the outcome of an asynchronous operation. + + +```java +public interface CompletionListener { + // Called when the associated operation completes successfully, + public void onSuccess(); + + // Called when the associated operation completes with an error. + public void onError(ErrorInfo reason); +} +``` + + + + +### ConnectionStateARTRealtimeConnectionStateConnection::STATEio.ably.lib.realtime.ConnectionStateIO.Ably.Realtime.ConnectionState + + + +`ConnectionState` is a String with a value matching any of the [Realtime Connection states](/docs/connect/states). + + +```javascript +var ConnectionStates = [ + 'initialized', + 'connecting', + 'connected', + 'disconnected', + 'suspended', + 'closing', + 'closed', + 'failed' +] +``` + + + + + + +`io.ably.lib.realtime.ConnectionState` is an enum representing all the [Realtime Connection states](/docs/connect/states). + + +```java +public enum ConnectionState { + initialized, // 0 + connecting, // 1 + connected, // 2 + disconnected, // 3 + suspended, // 4 + closing, // 5 + closed, // 6 + failed // 7 +} +``` + + + + + + +`IO.Ably.Realtime.ConnectionState` is an enum representing all the [Realtime Connection states](/docs/connect/states). + + +```csharp +public enum ConnectionState +{ + Initialized, //0 + Connecting, //1 + Connected, //2 + Disconnected, //3 + Suspended, //4 + Closing, //5 + Closed, //6 + Failed //7 +}; +``` + + + + + + +`Ably::Realtime::Connection::STATE` is an enum-like value representing all the [Realtime Connection states](/docs/connect/states). `STATE` can be represented interchangeably as either symbols or constants. + +#### Symbol states + + +```ruby +:initialized # => 0 +:connecting # => 1 +:connected # => 2 +:disconnected # => 3 +:suspended # => 4 +:closing # => 5 +:closed # => 6 +:failed # => 7 +``` + + +#### Constant states + + +```ruby +Connection::STATE.Initialized # => 0 +Connection::STATE.Connecting # => 1 +Connection::STATE.Connected # => 2 +Connection::STATE.Disconnected # => 3 +Connection::STATE.Suspended # => 4 +Connection::STATE.Closing # => 5 +Connection::STATE.Closed # => 6 +Connection::STATE.Failed # => 7 +``` + + +#### Example usage + + +```ruby +# Example with symbols +client.connection.on(:connected) { ... } + +# Example with constants +client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... } + +# Interchangeable +Ably::Realtime::Connection::STATE.Connected == :connected # => true +``` + + + + + + +`ARTRealtimeConnectionState` is an enum representing all the [Realtime Connection states](/docs/connect/states). + + + + +```objc +typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionState) { + ARTRealtimeInitialized, + ARTRealtimeConnecting, + ARTRealtimeConnected, + ARTRealtimeDisconnected, + ARTRealtimeSuspended, + ARTRealtimeClosing, + ARTRealtimeClosed, + ARTRealtimeFailed +}; +``` + + + + + + +```swift +public enum ARTRealtimeConnectionState : UInt { + case Initialized + case Connecting + case Connected + case Disconnected + case Suspended + case Closing + case Closed + case Failed +} +``` + + + + + + + +`ConnectionState` is an enum representing all the [Realtime Connection states](/docs/connect/states). + + +```go +const ( + StateConnInitialized = 1 + StateConnConnecting = 2 + StateConnConnected = 4 + StateConnDisconnected = 8 + StateConnSuspended = 16 + StateConnClosing = 32 + StateConnClosed = 64 + StateConnFailed = 128 +) +``` + + + + + + +`ably.ConnectionState` is an enum representing all the [Realtime Connection states](/docs/connect/states). + + +```flutter +enum ConnectionState { + initialized, + connecting, + connected, + disconnected, + suspended, + closing, + closed, + failed +} +``` + + + + +### ConnectionEventARTRealtimeConnectionEventConnection::EVENT Enumio.ably.lib.realtime.ConnectionEvent EnumIO.Ably.Realtime.ConnectionEvent Enum + + + +`ConnectionEvent` is a String that can be emitted as an event on the `Connection` object; either a [Realtime Connection state](/docs/connect/states) or an `update` event. + + +```javascript +var ConnectionEvents = [ + 'initialized', + 'connecting', + 'connected', + 'disconnected', + 'suspended', + 'closing', + 'closed', + 'failed', + 'update' +] +``` + + + + + + +`io.ably.lib.realtime.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [Realtime Connection state](/docs/connect/states) or an `update` event. + + +```java +public enum ConnectionEvent { + initialized, // 0 + connecting, // 1 + connected, // 2 + disconnected, // 3 + suspended, // 4 + closing, // 5 + closed, // 6 + failed, // 7 + update // 8 +} +``` + + + + + + +`IO.Ably.Realtime.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [Realtime Connection state](/docs/connect/states) or an `Update` event. + + +```csharp +public enum ConnectionState +{ + Initialized, //0 + Connecting, //1 + Connected, //2 + Disconnected, //3 + Suspended, //4 + Closing, //5 + Closed, //6 + Failed, //7 + update //8 +}; +``` + + + + + + +`Ably::Realtime::Connection::EVENT` is an enum-like value representing all the events that can be emitted be the `Connection`; either a [Realtime Connection state](/docs/connect/states) or an `:update` event. `EVENT` can be represented interchangeably as either symbols or constants. + +#### Symbol states + + +```ruby +:initialized # => 0 +:connecting # => 1 +:connected # => 2 +:disconnected # => 3 +:suspended # => 4 +:closing # => 5 +:closed # => 6 +:failed # => 7 +:update # => 8 +``` + + +#### Constant states + + +```ruby +Connection::EVENT.Initialized # => 0 +Connection::EVENT.Connecting # => 1 +Connection::EVENT.Connected # => 2 +Connection::EVENT.Disconnected # => 3 +Connection::EVENT.Suspended # => 4 +Connection::EVENT.Closing # => 5 +Connection::EVENT.Closed # => 6 +Connection::EVENT.Failed # => 7 +Connection::EVENT.Update # => 8 +``` + + +#### Example usage + + +```ruby +# Example with symbols +client.connection.on(:connected) { ... } + +# Example with constants +client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... } + +# Interchangeable +Ably::Realtime::Connection::STATE.Connected == :connected # => true +``` + + + + + + +`ARTRealtimeConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [Realtime Connection state](/docs/connect/states) or an `Update` event. + + + + +```objc +typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionEvent) { + ARTRealtimeConnectionEventInitialized, + ARTRealtimeConnectionEventConnecting, + ARTRealtimeConnectionEventConnected, + ARTRealtimeConnectionEventDisconnected, + ARTRealtimeConnectionEventSuspended, + ARTRealtimeConnectionEventClosing, + ARTRealtimeConnectionEventClosed, + ARTRealtimeConnectionEventFailed, + ARTRealtimeConnectionEventUpdate +}; +``` + + + + + + +```swift +public enum ARTRealtimeConnectionEvent : UInt { + case Initialized + case Connecting + case Connected + case Disconnected + case Suspended + case Closing + case Closed + case Failed + case Update +} +``` + + + + + + + +`ConnectionEvent` is a String that can be emitted as an event on the `Connection` object; either a [Realtime Connection state](/docs/connect/states) or an `update` event. + + +```go +const ( + StateConnInitialized = 1 + StateConnConnecting = 2 + StateConnConnected = 4 + StateConnDisconnected = 8 + StateConnSuspended = 16 + StateConnClosing = 32 + StateConnClosed = 64 + StateConnFailed = 128 +) +``` + + + + + + +`ably.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [Realtime Connection state](/docs/connect/states) or an `update` event. + + +```flutter +enum ConnectionEvent { + initialized, + connecting, + connected, + disconnected, + suspended, + closing, + closed, + failed, + update +} +``` + + + + + + + +### io.ably.lib.realtime.ConnectionStateListener + +A `io.ably.lib.realtime.ConnectionStateListener` is an interface allowing a client to be notified of connection state change. See [Connection#on](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. + + +```java +public interface ConnectionStateListener { + // Called when the connection state changes + public void onConnectionStateChanged(ConnectionStateListener.ConnectionStateChange state); +} +``` + + + + +### ConnectionStateChange ObjectARTConnectionStateChangeConnectionStateChangeio.ably.lib.realtime.ConnectionStateListener.ConnectionStateChangeIO.Ably.Realtime.ConnectionStateChange + +A `io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange``Ably::Models::ConnectionStateChange``ARTConnectionStateChange``IO.Ably.Realtime.ConnectionStateChange``ConnectionStateChange` is a type encapsulating state change information emitted by the [Connection](/docs/api/realtime-sdk/connection) object. See [Connection#on](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| currentCurrent | The new state | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| eventEvent | The event that triggered this state change | [`ConnectionEvent`](/docs/api/realtime-sdk/types#connection-event)[`Connection::EVENT`](/docs/api/realtime-sdk/types#connection-event) | +| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| retryInretry_inRetryIn | Duration upon which the library will retry a connection where applicable, as millisecondssecondsa `Timespan` | `Integer``Timespan``Long Integer` | + + + +### IO.Ably.PaginatedRequestParams + +`HistoryRequestParams` is a type that encapsulates the parameters for a history queries. For example usage see [`Channel#History`](/docs/api/realtime-sdk/history#channel-history). + +#### Members + +| Property | Description | Type | +|----------|-------------|------| +| Start | _null_ The start of the queried interval | `DateTimeOffset` | +| End | _null_ The end of the queried interval | `DateTimeOffset` | +| Limit | _null_ By default it is null. Limits the number of items returned by history or stats | `Integer` | +| Direction | _Backwards_ Enum which is either `Forwards` or `Backwards` | `Direction` enum | +| ExtraParameters | Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging. | `Dictionary` | + + + + + +### io.ably.lib.realtime.Channel.MessageListener + +A `io.ably.lib.realtime.Channel.MessageListener` is an interface allowing a client to be notified when messages are received on a channel using a [channel subscription](/docs/pub-sub#subscribe). + + +```java +public interface MessageListener { + // Called when one or more messages are received + public void onMessage(Message message); +} +``` + + + + + + +### LastConnectionDetails + +A `LastConnectionDetails` object provides details on the last connection in a browser environment persisted when the `window beforeunload` fired. This object is provided to the callback specified in the `recover` attribute of [`ClientOptions`](/docs/api/realtime-sdk/types#client-options). The callback in turn instructs the client library whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for more information. + +Please note that as [`sessionStorage`](https://www.w3.org/TR/webstorage/) is used to persist the `LastConnectionDetails` between page reloads, it is only available for pages in the same origin and top-level browsing context. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| recoveryKey | An opaque string obtained from the [recoveryKey](/docs/api/realtime-sdk/connection#recovery-key) attribute of the [Connection object](/docs/api/realtime-sdk/connection) before the page was unloaded. This property is used by the library to recover the connection | `String` | +| disconnectedAt | The time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch | `Integer` | +| location | A clone of [`location`](https://www.w3.org/TR/html5/browsers.html#the-location-interface) object of the previous page's `document` object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page | `String` | +| clientId | The [`clientId`](/docs/api/realtime-sdk/authentication/#client-id) of the [client's Auth object](/docs/api/realtime-sdk/authentication) before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user's `clientId` matches the previous connection's `clientId` before allowing the connection to be recovered. Ably prohibits changing a `clientId` for an existing connection, so any mismatch in `clientId` during a recover will result in the connection moving to the failed state | `String` | + + + + + +### io.ably.lib.realtime.Presence.PresenceListener + +A `io.ably.lib.realtime.Channel.MessageListener` is an interface allowing a client to be notified when messages are received on a channel using a [channel subscription](/docs/pub-sub#subscribe). + + +```java +public interface MessageListener { + // Called when one or more messages are received + public void onMessage(Message message); +} +``` + + + + + + +### Ably::Util::SafeDeferrable + +The `SafeDeferrable` class provides an [EventMachine](https://github.com/eventmachine/eventmachine) compatible [`Deferrable`](https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable). + +A `SafeDeferrable` ensures that any exceptions in callbacks provided by developers will not break the client library and stop further execution of code. + +#### Methods + +##### callback + +`callback(&block)` + +Specify a block to be executed if and when the `Deferrable` object receives a status of `:succeeded`. See the [EventMachine callback documentation](https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#callback-instance_method) + +##### errback + +`errback(&block)` + +Specify a block to be executed if and when the `Deferrable` object receives a status of `:failed`. See the [EventMachine errback documentation](https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#errback-instance_method) + +##### fail + +`fail(*args)` + +Mark the `Deferrable` as failed and trigger all callbacks. See the [EventMachine fail documentation](https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#fail-instance_method) + +##### succeed + +`succeed(*args)` + +Mark the `Deferrable` as succeeded and trigger all callbacks. See the [EventMachine succeed documentation](https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#succeed-instance_method) + + + + + +### IO.Ably.StatsRequestParams + +`HistoryRequestParams` is a type that encapsulates the parameters for a history queries. For example usage see [`Channel#History`](/docs/api/realtime-sdk/history#channel-history). + +#### Members + +| Property | Description | Type | +|----------|-------------|------| +| Start | _null_ The start of the queried interval | `DateTimeOffset` | +| End | _null_ The end of the queried interval | `DateTimeOffset` | +| Limit | _null_ By default it is null. Limits the number of items returned by history or stats | `Integer` | +| Direction | _Backwards_ Enum which is either `Forwards` or `Backwards` | `Direction` enum | +| ExtraParameters | Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging. | `Dictionary` | + + + +### TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams + + + +`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following attributes can be defined on the object: + + + + + +`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following key symbol values can be added to the Hash: + + + + + +`TokenParams` is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). + + + + + +`ARTTokenParams` is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). + + + +#### PropertiesMembersAttributes + +| Property | Description | Type | +|----------|-------------|------| +| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | +| clientIdClientId:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``:client_id``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``:client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``:client_id``ClientId` specified here conflicts with the `clientId``:client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | +| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | +| ttlTtl:ttl | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | + + + +### TokenRevocationTargetSpecifier + +`TokenRevocationTargetSpecifier` + +A `TokenRevocationTargetSpecifier` describes which tokens should be affected by a token revocation request. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| type | The type of token revocation target specifier. Valid values include `clientId`, `revocationKey` and `channel` | `String` | +| value | The value of the token revocation target specifier | `String` | + +### TokenRevocationOptions + +`TokenRevocationOptions` + +A `TokenRevocationOptions` describes the additional options accepted by revoke tokens request. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| issuedBefore | An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an `issuedBefore` in the future, or more than an hour in the past, will be rejected | `Number` | +| allowReauthMargin | _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is `false`, meaning that the effect is near-immediate. | `Boolean` | + +