Types

The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments.

Where client libraries support both Realtime and REST APIs, the types are shared between both clients.

All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object.

If you are interested in finding out more about the exact types and options definitions in each language, we recommend you download our open source libraries and review the code.

Data types

io.ably.lib.types.AblyExceptionAbly::Exceptions::BaseAblyExceptionIO.Ably.AblyException

ErrorInfoARTErrorInfoio.ably.lib.types.ErrorInfoAbly::Models::ErrorInfoIO.Ably.ErrorInfo

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

PropertiesMembersAttributes

codeCode

Ably error code (see ably-common/protocol/errors.json)
Type: Integer

statusCodestatus_codeStatusCode

HTTP Status Code corresponding to this error, where applicable
Type: Integer

messageMessage

Additional message information, where available
Type: String

MessageARTMessageio.ably.lib.types.MessageAbly::Models::MessageIO.Ably.Message

A Message represents an individual message that is sent to or received from Ably.

PropertiesMembersAttributesAttributes

nameName

Event name, if provided
Type: String

data

The message payload, if provided
Type: String, StringBuffer, JSON Object

data

The message payload, if provided
Type: String, ByteArray, JSONObject, JSONArray

Data

The message payload, if provided
Type: String, byte[], plain C# object that can be serialized to Json

data

The message payload, if provided
Type: String, Binary (ASCII-8BIT String), Hash, Array

data

The message payload, if provided
Type: String, Bytearray, Dict, List

data

The message payload, if provided
Type: String, Binary String, Associative Array, Array

data

The message payload, if provided
Type: NSString *, NSData *, NSDictionary *, NSArray *

data

The message payload, if provided
Type: String, NSData, Dictionary, Array

idId

Unique ID assigned by Ably to this message
Type: String

clientIdclient_idClientId

The client ID of the publisher of this message
Type: String

connectionIdconnection_idConnectionId

The connection ID of the publisher of this message
Type: String

timestampTimestamp

Timestamp when the presence update was received by the Ably the realtime service, as milliseconds since the epocha Time object
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate

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

Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction

var allPresenceActions = [
  'absent', // (reserved for internal use)
  'present',
  'enter',
  'leave',
  'update'
]

public enum Action {
  ABSENT,  // 0 (reserved for internal use)
  PRESENT, // 1
  ENTER,   // 2
  LEAVE,   // 3
  UPDATE   // 4
}

public enum Action {
  Absent,  // 0 (reserved for internal use)
  Present, // 1
  Enter,   // 2
  Leave,   // 3
  Update   // 4
}

class PresenceAction(object):
  ABSENT = 0    # (reserved for internal use)
  PRESENT = 1
  ENTER = 2
  LEAVE = 3
  UPDATE = 4

namespace Ably\Models;
class PresenceMessages {
  const ABSENT  = 0; /* (reserved for internal use) */
  const PRESENT = 1;
  const ENTER   = 2;
  const LEAVE   = 3;
  const UPDATE  = 4;
}

if ($presenceMessage->action == Ably\Models\PresenceMesage::ENTER) {
  /* do something */
}

:absent  # => 0 (reserved for internal use)
:present # => 1
:enter   # => 2
:leave   # => 3
:update  # => 4

PresenceMessage::ACTION.Absent  # => 0 (internal use)
PresenceMessage::ACTION.Present # => 1
PresenceMessage::ACTION.Enter   # => 2
PresenceMessage::ACTION.Leave   # => 3
PresenceMessage::ACTION.Update  # => 4

# Example with symbols
presence.on(:attached) { ... }

# Example with constants
presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }

# Interchangeable
Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true

typedef NS_ENUM(NSUInteger, ARTPresenceAction) {
    ARTPresenceAbsent, // reserved for internal use
    ARTPresencePresent,
    ARTPresenceEnter,
    ARTPresenceLeave,
    ARTPresenceUpdate,
    ARTPresenceLast
};

enum ARTPresenceAction : UInt {
  case Absent // reserved for internal use
  case Present
  case Enter
  case Leave
  case Update
  case Last
}

PresenceMessageARTPresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageIO.Ably.PresenceMessage

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

PropertiesMembersAttributes

action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

Action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: enum { Absent, Present, Enter, Leave, Update }

action

the event signified by a PresenceMessage. See Presence action
Type: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

action

the event signified by a PresenceMessage. See PresenceAction
Type: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

action

the event signified by a PresenceMessage. See PresenceMessage::ACTION
Type: enum { :absent, :present, :enter, :leave, :update }

action

the event signified by a PresenceMessage. See PresenceMessage::ACTION
Type: const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE

action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: ARTPresenceAction

data

The presence update payload, if provided
Type: String, ByteArray, JSONObject, JSONArray

Data

The presence update payload, if provided
Type: String, byte[], plain C# object that can be converted to Json

data

The presence update payload, if provided
Type: String, StringBuffer, JSON Object

data

The presence update payload, if provided
Type: String, Binary (ASCII-8BIT String), Hash, Array

data

The presence update payload, if provided
Type: String, Bytearray, Dict, List

data

The message payload, if provided
Type: String, NSData, Dictionary, Array

data

The message payload, if provided
Type: NSString *, NSData *, NSDictionary *, NSArray *

data

The message payload, if provided
Type: String, Binary String, Associative Array, Array

idId

Unique ID assigned by Ably to this presence update
Type: String

clientIdclient_idClientId

The client ID of the publisher of this presence update
Type: String

connectionIdconnection_idConnectionId

The connection ID of the publisher of this presence update
Type: String

timestampTimestamp

Timestamp when the presence update was received by the Ably the realtime service, as milliseconds since the epoch.
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate

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
Type: String

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 is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.

PropertiesMembersAttributesAttributes

itemsItems

contains a page of results (for example an Array of Message or PresenceMessage objects for a channel history request)
Type: Array <Message, Presence, Stats>Type: List <Message, Presence, Stats>

isLast

true if this page is the last page
Type: Boolean

last?

true if this page is the last page
Type: Boolean

isLast()

true if this page is the last page
Type: Boolean

is_last()

True if this page is the last page
Type: Boolean

hasNext

true if there are further pages
Type: Boolean

HasNext

true if there are further pages
Type: Boolean

has_next?

true if there are further pages
Type: Boolean

hasNext()

true if there are further pages
Type: Boolean

has_next()

True if there are further pages
Type: Boolean

Methods

firstFirst

first(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult firstPaginatedResult first()PaginatedResult first()Task<PaginatedResult> FirstAsync()PaginatedResult first()first(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.The method is asynchronous and returns a Task which needs to be awaited to get the PaginatedResult.

itemsItems

Object[] items()List items()Object[] itemsObject[] items()List Itemsitems: [AnyObject]

Returns the current page of results as an Arraya Lista List. The type of the objects in the arraylist is determined by the operation that provided the PaginatedResult. For example, a Message.history()Message.History() request will return an arraya list of Message objects.

nextNext

next(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult nextPaginatedResult next()PaginatedResult next()Task<PaginatedResult> NextAsync()PaginatedResult next()next(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then nulla blank PaginatedResult will be returnedNullNonenil is returned. The method is asynchronous and return a Task which needs to be awaited to get the PaginatedResultWhen using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

Example

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast;
  });
});

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast;
  });
});

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

PaginatedResult<Message> 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);
}

# 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

result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())

$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}

[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast);
    }];
}];

channel.history { paginatedResult, error in
    let paginatedResult = paginatedResult!
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        let nextPage = nextPage!
        print("Page 0 item 0: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast)")
    }
}

io.ably.lib.types.Param

TokenDetailsARTTokenDetailsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetailsIO.Ably.TokenDetails

TokenDetails is a type providing details of the token string and its associated metadata.

PropertiesMembersAttributes

tokenToken

The token itself. A typical token string may appear like xVLyHw.A-pwh7wAiq4a9gPy0yQQU3A9RZZw-h-yBapnZwjDC-k0ctFOVg
Type: String

expiresExpires

The time (in milliseconds since the epoch)The time at which this token expires
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate

issuedIssued

The time (in milliseconds since the epoch)The time at which this token was issued
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate

capabilityCapability

The capability associated with this token. The capability is a a JSON stringified canonicalised representation of the resource paths and associated operations. Read more about authentication and capabilities
Type: StringCapability

clientIdclient_idClientId

The client ID, if any, bound to this token. If a client ID is included, then the token authenticates its bearer as that client ID, and the token may only be used to perform operations on behalf of that client ID. The client is then considered to be an identified client
Type: String

TokenRequestARTTokenRequestio.ably.lib.types.TokenRequestAbly::Models::TokenRequestIO.Ably.TokenRequest

TokenRequest is a type containing parameters for a token request. Tokens are requested using Auth#requestTokenAuth#request_token

PropertiesMembersAttributes

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
Type: String

ttlTtl

Requested time to live for the token in millisecondsin secondsas a TimeSpan. If the token request is successful, the TTL of the returned token will be less than or equal to this value depending on application settings and the attributes of the issuing key.
Type: IntegerTimeSpan

timestampTimestamp

The timestamp of this request in milliseconds
Type: IntegerLong IntegerTimeDateTimeOffset

capabilityCapability

Capability of the token. If the token request is successful, the capability of the returned token will be the intersection of this capability with the capability of the issuing key. The capability is a a JSON stringified canonicalised representation of the resource paths and associated operations. Read more about authentication and capabilities
Type: String

clientIdclient_idClientId

The client ID to associate with this token. When provided, the token may only be used to perform operations on behalf of that client ID
Type: String

nonceNonce

An opaque nonce string of at least 16 characters
Type: String

macMac

The Message Authentication Code for this request
Type: String

Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.Stats

A Stats object represents a application statistic for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.

Please note that most attributes of the Stats type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby and Python however uses under_score case instead of the default camelCase in most languages, so please bear that in mind.

PropertiesMembersAttributesKeyword arguments

allAll

aggregate count of both inbound and outbound message stats
Type: MessageTypes

apiRequestsapi_requestsApiRequests

breakdown of API requests received via the Ably REST API
Type: RequestCount

channelsChannels

breakdown of channel related stats such as min, mean and peak channels
Type: ResourceCount

connectionsConnections

breakdown of connection related stats such as min, mean and peak channels for TLS and non-TLS connections
Type: ConnectionTypes

inboundInbound

statistics such as count and data for all inbound messages received over REST and Realtime connection, organized into normal channel messages or presence messages
Type: MessageTraffic

interval_granularityIntervalGranularity

A GRANULARITY constantvalueEnum representing the granularity (interval) of this statistic such as :minute, :hour, :day, :month'minute', 'hour', 'day', 'month'Minute, Hour, Day, Month.
Type: Stats::GRANULARITYStringStatsIntervalGranularity enum

intervalIdinterval_idIntervalId

the interval ID provides both the time from which the interval starts as well as the length of time that this statistic covers i.e. the period of time which the stats are aggregated for. For example, an interval ID value of “2016-03-01:10:02” represents a single minute interval for the UTC time presented in the string. However, an interval ID of “2016-03” represents a month interval for the entire month of March 2016 based on UTC time.
Type: String

interval_timeIntervalTime

A TimeDateTimeDateTimeOffset object representing the start of the interval
Type: TimeDateTimeDateTimeOffset

outboundOutbound

statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with WebHooks, organized into normal channel messages or presence messages
Type: MessageTraffic

persistedPersisted

messages persisted and later retrieved via the history API
Type: MessageTypes

tokenRequeststoken_requestsTokenRequests

breakdown of Token requests received via the Ably REST API.
Type: RequestCount

ARTStatsGranularity

typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
    ARTStatsGranularityMinute,
    ARTStatsGranularityHour,
    ARTStatsGranularityDay,
    ARTStatsGranularityMonth
};

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

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

Other types

AuthOptions ObjectARTAuthOptionsAuthOptions Hashio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions

PropertiesMembersAttributesAttributes

authCallbackAuthCallbackauth_callback:auth_callback

A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda which is called when a new token is required. The role of the callback is to either generate a signed TokenRequest which may then be submitted automatically by the library to the Ably REST API requestToken; or to provide a valid token in as a TokenDetails object. See an authentication callback example or our authentication documentation for details of the token request format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>

authUrlAuthUrl:auth_urlauth_url

A URL that the library may use to obtain a token string (in plain text format), or a signed TokenRequest or TokenDetails (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.
Type: StringUri

authMethodAuthMethod:auth_methodauth_method

GET:get The HTTP verb to use for the request, either GET:get or POST:post
Type: StringSymbolHttpMethod

authHeadersAuthHeaders:auth_headersauth_headers

A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response.
Type: ObjectHashAssociative ArrayParam[]Dictionary<string, string>

authParamsAuthParams:auth_paramsauth_params

A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is GET, query params are added to the URL, whereas when authMethodAuthMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type: ObjectHashAssociative ArrayParam[]Dictionary<string, string>

forceForce:forceforce

false When true, this indicates to authorizeAuthorize that a new token should be requested, even if the current token is still valid
Type: Boolean

keyKey:keykey

Optionally the API key to use can be specified as a full key string; if not, the API key passed into ClientOptions when instancing the Realtime or REST library is used
Type: String

queryTimeQueryTime:query_timequery_time

false If true, the library will query the Ably servers for the current time instead of relying on a locally-available time of day
Type: Boolean

tokenToken:tokentoken

An authenticated token string that is most commonly obtained from the tokenToken property of a TokenDetails component of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: String

tokenDetailsTokenDetails:token_detailstoken_details

An authenticated TokenDetails object that is most commonly obtained from of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails

useTokenAuthUseTokenAuth:use_token_authuse_token_auth

false When true, forces Token authentication to be used by the library. Please note that if a client_idClientIdclientId is not specified in the ClientOptions or TokenParams, then the token issued will be anonymous
Type: Boolean

ARTChannelEvent

typedef NS_ENUM(NSUInteger, ARTChannelEvent) {
    ARTChannelEventInitialized,
    ARTChannelEventAttaching,
    ARTChannelEventAttached,
    ARTChannelEventDetaching,
    ARTChannelEventDetached,
    ARTChannelEventFailed,
    ARTChannelEventError
};

enum ARTChannelEvent : UInt {
    case Initialized
    case Attaching
    case Attached
    case Detaching
    case Detached
    case Failed
    case Error
}

ClientOptions ObjectARTClientOptionsClientOptions Hashio.ably.lib.types.ClientOptionsIO.Ably.ClientOptions

PropertiesMembersAttributesKeyword arguments

keyKey:key

The full key string, as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue tokens without needing to defer to a separate entity to sign token requests. Read more about Basic authentication
Type: String

tokenToken:token

An authenticated token string that is most commonly obtained from the @[email protected]>Token property of a TokenDetails component of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: String

tokenDetailsTokenDetailstoken_details:token_details

An authenticated TokenDetails object that is most commonly obtained from of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails

tlsTls:tls

true A boolean value, indicating whether or not a TLS (“SSL”) secure connection should be used. An insecure connection cannot be used with Basic authentication ensuring private keys are compromised in transit. Find out more about TLS
Type: Boolean

clientIdClientIdclient_id:client_id

A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_id specified here conflicts with the clientIdclient_idClientId implicit in the token. Find out more about client identities
Type: String

authCallbackAuthCallbackauth_callback:auth_callback

A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda which is called when a new token is required. The role of the callback is to either generate a signed TokenRequest which may then be submitted automatically by the library to the Ably REST API requestToken; or to provide a valid token in as a TokenDetails object. See an authentication callback example or our authentication documentation for details of the token request format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>

authUrlAuthUrlauth_url:auth_url

A URL that the library may use to obtain a token string (in plain text format), or a signed TokenRequest or TokenDetails (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.
Type: StringUri

authMethodAuthMethodauth_method:auth_method

GET:get The HTTP verb to use for the request, either GET:get or POST:post
Type: StringSymbolHttpMethod

authHeadersAuthHeadersauth_headers:auth_headers

A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>

authParamsAuthParamsauth_params:auth_params

A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is GET, query params are added to the URL, whereas when authMethodAuthMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>

useTokenAuthUseTokenAuthuse_token_auth:use_token_auth

false When true, forces Token authentication to be used by the library. Please note that if a client_idclientId is not specified in the ClientOptions or TokenParams, then the token issued will be anonymous.
Type: Boolean

useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol

true If set to false, will forcibly disable the binary protocol. The binary protocol is used by default unless it isNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type: Boolean

queueMessagesQueueMessages:queue_messages

true If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states. The default behaviour 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 queuing if they wish to have application-level control over the queueing under those conditions
Type: Boolean

echoMessagesEchoMessages:echo_messages

true If false, prevents messages originating from this connection being echoed back on the same connection
Type: Boolean

autoConnectAutoConnect:auto_connect

true By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the connect method
Type: Boolean

recover

This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See connection state recovery for further information
Type: String, Callable

closeOnUnload

true When true, the client library will automatically send a close request to Ably whenever the window beforeunload event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the channel will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the close method of the Connection object, Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid “twitchy” presence behaviour an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes
Type: Boolean

recoverRecover:recover

This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection’s recoveryKeyrecovery_key. This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See connection state recovery for further information and example code
Type: String

queryTimeQueryTime:query_time

false If true, the library will query the Ably servers for the current time instead of relying on a locally-available time of day
Type: Boolean

defaultTokenParamsDefaultTokenParams:default_token_params

When a TokenParams object is provided, it will override the client library defaults when issuing new tokens or token requests
Type: TokenParams

disconnectedRetryTimeoutDisconnectedRetryTimeout:disconnected_retry_timeout

15,000ms15s When the connection enters the DISCONNECTED state, after this delay in millisecondsin secondsas a NSTimeInterval, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically
Type: IntegerNSTimeInterval

suspendedRetryTimeoutSuspendedRetryTimeout:suspended_retry_timeout

30,000ms30s When the connection enters the SUSPENDED state, after this delay in millisecondsin secondsas a NSTimeInterval, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
Type: IntegerNSTimeInterval

ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelptionsIO.Ably.Rest.ChannelOptions

Currently the supported channel options are only used for configuring encryption.

PropertiesMembersAttributes

cipher: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
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key

ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enum

var allChannelStates = [
  'initialized',
  'attaching',
  'attached',
  'detaching',
  'detached',
  'failed'
]

public enum ChannelState {
  initialized,  // 0
  attaching,    // 1
  attached,     // 2
  detaching,    // 3
  detached,     // 4
  failed        // 5
}

public enum ChannelState
{
    Initialized = 0,
    Attaching = 1,
    Attached = 2,
    Detaching= 3,
    Detached = 4,
    Failed = 5
};

:initialized # => 0
:attaching # =>   1
:attached # =>    2
:detaching # =>   3
:detached # =>    4
:failed # =>      5

Connection::STATE.Initialized # => 0
Connection::STATE.Attaching # =>   1
Connection::STATE.Attached # =>    2
Connection::STATE.Detaching # =>   3
Connection::STATE.Detached # =>    4
Connection::STATE.Failed # =>      5

# Example with symbols
channel.on(:attached) { ... }

# Example with constants
channel.on(Ably::Realtime::Channel::STATE.Attached) { ... }

# Interchangeable
Ably::Realtime::Channel::STATE.Attached == :attached # => true

typedef NS_ENUM(NSUInteger, ARTRealtimeChannelState) {
    ARTRealtimeChannelInitialized,
    ARTRealtimeChannelAttaching,
    ARTRealtimeChannelAttached,
    ARTRealtimeChannelDetaching,
    ARTRealtimeChannelDetached,
    ARTRealtimeChannelFailed
};

public enum ARTRealtimeChannelState : UInt {
    case Initialized
    case Attaching
    case Attached
    case Detaching
    case Detached
    case Failed
}

io.ably.lib.realtime.ChannelStateListener

public interface ChannelStateListener {
  // Called when the channel state changes
  public void onChannelStateChanged(ChannelState state, 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()Crypto.GetDefaultParams()Crypto.get_default_params(), or generating one automatically when initializing a channel, as in this example.

PropertiesMembersAttributes

keyKey:key

A binary (byte[]ArrayBuffer or WordArrayBufferbyte arrayNSData) containing the secret key used for encryption and decryption

algorithm:algorithmAlgorithm

AES The name of the algorithm in the default system provider, or the lower-cased version of it; eg “aes” or “AES”
Type: String

key_length:key_lengthkeyLengthKeyLength

256_128 The key length in bits of the cipher, either 128 or 256
Type: Integer_

mode:modeMode

CBC The cipher mode
Type: StringCipherMode

keySpec

A KeySpec for the cipher key
Type: SecretKeySpec

io.ably.lib.realtime.CompletionListener

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

var allConnectionStates = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed'
]

public enum ConnectionState {
  initialized,   // 0
  connecting,    // 1
  connected,     // 2
  disconnected,  // 3
  suspended,     // 4
  closing,       // 5
  closed,        // 6
  failed         // 7
}

public enum ConnectionState
{
    Initialized,    //0
    Connecting,     //1
    Connected,      //2
    Disconnected,   //3
    Suspended,      //4
    Closing,        //5
    Closed,         //6
    Failed          //7
};

:initialized # =>  0
:connecting # =>   1
:connected # =>    2
:disconnected # => 3
:suspended # =>    4
:closing # =>      5
:closed # =>       6
:failed # =>       7

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

typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionState) {
    ARTRealtimeInitialized,
    ARTRealtimeConnecting,
    ARTRealtimeConnected,
    ARTRealtimeDisconnected,
    ARTRealtimeSuspended,
    ARTRealtimeClosing,
    ARTRealtimeClosed,
    ARTRealtimeFailed
};

public enum ARTRealtimeConnectionState : UInt {
    case Initialized
    case Connecting
    case Connected
    case Disconnected
    case Suspended
    case Closing
    case Closed
    case Failed
}

io.ably.lib.realtime.ConnectionStateListener

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.ConnectionStateChangeAbly::Models::ConnectionStateChangeARTConnectionStateChangeIO.Ably.Realtime.ConnectionStateChangeConnectionStateChange is a type encapsulating state change information emitted by the Connection object. See Connection#on to register a listener for one or more events.

PropertiesMembersAttributes

previousPrevious

the previous state
Type: State StringConnection::STATEConnectionState

currentCurrent

the new state
Type: State StringConnection::STATEConnectionState

reasonReason

an ErrorInfo containing any information relating to the transition
Type: ErrorInfo

retryInretry_inRetryIn

Duration upon which the library will retry a connection where applicable, as millisecondssecondsa Timespan
Type: IntegerTimespanLong Integer

IO.Ably.HistoryRequestParams

io.ably.lib.realtime.Channel.MessageListener

public interface MessageListener {
  // Called when one or more messages are received
  public void onMessage(Message message);
}

LastConnectionDetails

io.ably.lib.realtime.Presence.PresenceListener

public interface MessageListener {
  // Called when one or more messages are received
  public void onMessage(Message message);
}

IO.Ably.StatsRequestParams

TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams

PropertiesMembersAttributesAttributes

capabilityCapability:capability

JSON stringified capability of the token. If the token request is successful, the capability of the returned token will be the intersection of this capability with the capability of the issuing key. Find our more about how to use capabilities to manage access privileges for clients. Type: StringCapability

clientIdClientIdclient_id:client_id

A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_idClientId specified here conflicts with the clientIdclient_idClientId implicit in the token. Find out more about client identities
Type: 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.
Type: 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 token requests from being replayed.
Type: IntegerLong IntegerTimeNSDateDateTimeOffset

ttlTtl:ttl

1 hour Requested time to live for the token being created in millisecondsin secondsas a NSTimeIntervalas a TimeSpan. When omitted, the Ably REST API default of 60 minutes is applied by Ably
Type: Integer (milliseconds)Integer (seconds)NSTimeIntervalLong IntegerTimeSpan