Types

The Ably REST 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.

REST Data types

io.ably.lib.types.AblyExceptionAbly::Exceptions::BaseAblyExceptionAblyExceptionAbly\Exceptions\AblyExceptionIO.Ably.AblyException

ChannelDetails

ChannelDetails is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.

channelId

the required name of the channel including any qualifier, if any
Type: string

region

in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type: 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
Type: boolean

status

an optional ChannelStatus instance
Type: ChannelStatus

The following is an example of a ChannelDetails JSON object:

{
  "channelId": "foo",
  "status": {
    "isActive": true,
    "occupancy": {
      "metrics": {
        "connections": 1,
        "publishers": 1,
        "subscribers": 1,
        "presenceConnections": 1,
        "presenceMembers": 0,
        "presenceSubscribers": 1
      }
    }
  }
}

ChannelDetails.ChannelStatus

ChannelStatus is contained within the ChannelDetails object, and optionally contains an Occupancy object.

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

occupancy

an optional 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.
Type: Occupancy

ChannelDetails.ChannelStatus.Occupancy

Occupancy is optionally contained within the ChannelStatus object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy attribute of the ChannelStatus object.

The occupancy attribute contains the metrics attribute, which contains the following members:

connections

the number of connections
Type: integer

publishers

the number of connections attached to the channel that are authorised to publish
Type: integer

subscribers

the number of connections attached that are authorised to subscribe to messages
Type: integer

presenceSubscribers

the number of connections that are authorised to subscribe to presence messages
Type: integer

presenceConnections

the number of connections that are authorised to enter members into the presence channel
Type: integer

presenceMembers

the number of members currently entered into the presence channel
Type: integer

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

{{/LANG_BLOCK}}

MessageARTMessageio.ably.lib.types.MessageAbly::Models::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

dataData

The presence update payload, if provided
Type: String, ByteArray, JSONObject, JSONArrayString, byte[], plain C# object that can be converted to JsonString, []byteString, StringBuffer, JSON ObjectString, Binary (ASCII-8BIT String), Hash, ArrayString, Bytearray, Dict, ListString, NSData, Dictionary, ArrayNSString *, NSData *, NSDictionary *, NSArray *String, Binary String, Associative Array, ArrayObject

extrasExtras

Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the push object.
Type: JSONObject, JSONArrayplain C# object that can be converted to JsonString, []byteJSON ObjectHash, ArrayDict, ListDictionary, ArrayNSDictionary *, NSArray *Associative Array, ArrayMap, List

idId

Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of idempotent publishing
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 message was received by the Ably service, as milliseconds since the epocha Time object
Type: IntegerLong IntegerDateTimeOffsetTimeNSDateDateTime

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

Message constructors

Message.fromEncoded

Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) → Message

A static factory method to create a Message from a deserialized Message-like object encoded using Ably’s wire protocol.

Parameters

encodedMsg

a Message-like deserialized object.
Type: Object

channelOptions

an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.
Type: Object

Returns

A Message object

Message.fromEncodedArray

Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) → Message[]

A static factory method to create an array of Messages from an array of deserialized Message-like object encoded using Ably’s wire protocol.

Parameters

encodedMsgs

an array of Message-like deserialized objects.
Type: Array

channelOptions

an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.
Type: Object

Returns

An Array of Message objects

PresenceMessageARTPresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::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

Action

the event signified by a PresenceMessage. See PresenceMessage::action
Type: const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate

dataData

The presence update payload, if provided
String, ByteArray, JSONObject, JSONArrayString, byte[], plain C# object that can be converted to JsonString, StringBuffer, JSON ObjectString, []byteString, Binary (ASCII-8BIT String), Hash, ArrayString, Bytearray, Dict, ListString, NSData, Dictionary, ArrayNSString *, NSData *, NSDictionary *, NSArray *String, Binary String, Associative Array, Array

extrasExtras

Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the push object.
Type: JSONObject, JSONArrayplain C# object that can be converted to JsonString, []byteJSON ObjectHash, ArrayDict, ListDictionary, ArrayNSDictionary *, NSArray *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 Ably, 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

PresenceMessage constructors

PresenceMessage.fromEncoded

PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) → PresenceMessage

A static factory method to create a PresenceMessage from a deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsg

a PresenceMessage-like deserialized object.
Type: Object

channelOptions

an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.
Type: Object

Returns

A PresenceMessage object

PresenceMessage.fromEncodedArray

PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) → PresenceMessage[]

A static factory method to create an array of PresenceMessages from an array of deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsgs

an array of PresenceMessage-like deserialized objects.
Type: Array

channelOptions

an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.
Type: Object

Returns

An Array of PresenceMessage objects

Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONAbly\Models\PresenceMessage ActionIO.Ably.PresenceAction

var PresenceActions = [
  '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
};

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

const (
  PresenceAbsent = 0
  PresencePresent = 1
  PresenceEnter = 2
  PresenceLeave = 3
  PresenceUpdate = 4
)

PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::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.

PropertiesMembersAttributes

itemsItems

contains the current 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>

Methods

firstFirst

first(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult firstPaginatedResult first()PaginatedResult first()Task<PaginatedResult> 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 and yields a PaginatedResult.The method is asynchronous and returns a Task which needs to be awaited to get the PaginatedResult.

hasNextHasNexthas_next?has_next

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

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

isLastIsLastlast?is_last

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

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

nextNext

next(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult nextPaginatedResult next()PaginatedResult next()Task<PaginatedResult> 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 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 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 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}

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, which is a type that represents a page of results plus metadata indicating the relative queries available to it. HttpPaginatedResponse additionally carries information about the response to an HTTP request. It is used when making custom HTTP requests.

PropertiesMembersAttributesAttributes

itemsItems

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

statusCodestatus_codeStatusCode

the HTTP status code of the response
Type: Number

successSuccess

whether that HTTP status code indicates success (equivalent to 200 <= statusCode < 300)
Type: Boolean

headersHeaders

the response’s headers
Type: Object

Methods

firstFirst

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

Returns a new HttpPaginatedResponse for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields an HttpPaginatedResponse.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/api/realtime-sdk/types#http-paginated-response.

hasNextHasNexthas_next?has_next

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

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

isLastIsLastlast?is_last

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

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

nextNext

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

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

Example

The HttpPaginatedResponse interface is a superset of PaginatedResult, see the PaginatedResult example

io.ably.lib.types.Param

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

TokenDetails is a type providing details of Ably Token string and its associated metadata.

PropertiesMembersAttributes

tokenToken

The Ably Token itself. A typical Ably Token string may appear like xVLyHw.A-pwh7wR9LihfnuyRs28QCPGgNuNnP5fpiNbMZlunrwHD48YHg
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 Ably Token. The capability is a a JSON stringified canonicalized 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 Ably Token. If a client ID is included, then the Ably Token authenticates its bearer as that client ID, and the Ably 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

TokenDetails constructors

TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap

TokenDetails.fromJson(String json) → TokenDetailsTokenDetails.from_json(String json) → TokenDetailsTokenDetails.fromMap(Map<String, dynamic> map)

A static factory methodnamed constructor to create a TokenDetails from a deserialized TokenDetails-like object or a JSON stringified TokenDetailsmap. 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 fromJsonfromMap method when constructing a TokenDetails, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenDetails object

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

TokenRequest is a type containing parameters for an Ably TokenRequest. Ably 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 Ably Token in millisecondsin secondsas a TimeSpan. If the Ably TokenRequest is successful, the TTL of the returned Ably Token will be less than or equal to this value depending on application settings and the attributes of the issuing key.
Type: IntegerTimeSpanNSTimeInterval

timestampTimestamp

The timestamp of this request in milliseconds
Type: IntegerLong IntegerTimeDateTimeOffsetNSDate

capabilityCapability

Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned Ably Token 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
Type: String

clientIdclient_idClientId

The client ID to associate with the requested Ably Token. When provided, the Ably 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

TokenRequest constructors

TokenRequest.fromJsonTokenRequest.from_jsonTokenRequest.fromMap

TokenRequest.fromJson(String json) → TokenRequestTokenRequest.from_json(String json) → TokenRequestTokenRequest.fromMap(Map<String, dynamic> map)

A static factory methodnamed constructor to create a TokenRequest from a deserialized TokenRequest-like object or a JSON stringified TokenRequest/span>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 fromJsonfromMap method when constructing a TokenRequest, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenRequest object

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

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

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

PropertiesMembersAttributesKeyword arguments

unit

the length of the interval that this statistic covers, such as :minute, :hour, :day, :monthMinute, Hour, Day, MonthStatGranularityDay, StatGranularityMonth'minute', 'hour', 'day', 'month'.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString

interval_granularityintervalGranularity

Deprecated alias for unit; scheduled to be removed in version 2.x client library versions.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString

intervalIdinterval_idIntervalId

the UTC time at which the time period covered by this Stats object starts. For example, an interval ID value of “2018-03-01:10” in a Stats object whose unit is day would indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11”. All Stats objects, except those whose unit is minute, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the unit by looking at the resolution of the intervalId. Stats objects covering an individual minute will have an interval ID indicating that time; for example “2018-03-01:10:02”.
Type: String

interval_timeIntervalTime

A TimeDateTimeDateTimeOffset object representing the parsed intervalIdinterval_idIntervalId (the UTC time at which the time period covered by this Stats object starts)
Type: TimeDateTimeDateTimeOffset

allAll

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

apiRequestsapi_requestsApiRequests

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

channelsChannels

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

connectionsConnections

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

inboundInbound

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

outboundOutbound

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

persistedPersisted

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

tokenRequeststoken_requestsTokenRequests

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

pushPush

Detailed stats on push notifications, see our Push documentation for more details
Type: PushStats

ARTStatsGranularity

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
}

IO.Ably.PaginatedRequestParams

REST Other types

AuthOptions ObjectARTAuthOptionsAuthOptions HashAuthOptions Arrayio.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 (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>

authUrlAuthUrl:auth_urlauth_url

A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
Type: StringUriNSURL

authMethodAuthMethodauth_method:auth_method

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

authHeadersAuthHeadersauth_headers:auth_headers

A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an authorization key, then withCredentials will be set on the xhr request.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>Map<String, String>

authParamsAuthParams:auth_paramsauth_params

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

tokenDetailsTokenDetailstoken_details:token_details

An authenticated TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails

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 when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
Type: Boolean

tokenToken:token

An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the tokenToken property of a TokenDetails component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type: String, TokenDetails or TokenRequest

ClientOptions ObjectARTClientOptionsClientOptions HashClientOptions Arrayio.ably.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 Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authentication
Type: String

tokenToken:token

An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the tokenToken property of a TokenDetails component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type: String, TokenDetails or TokenRequest

authCallbackAuthCallbackauth_callback:auth_callback

A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>

authUrlAuthUrl:auth_urlauth_url

A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
Type: StringUriNSURL

authMethodAuthMethodauth_method:auth_method

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

authHeadersAuthHeadersauth_headers:auth_headers

A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an authorization key, then withCredentials will be set on the xhr request.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>Map<String, String>

authParamsAuthParams:auth_paramsauth_params

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

tokenDetailsTokenDetailstoken_details:token_details

An authenticated TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails

tlsTls:tls

true A boolean value, indicating whether or not a TLS (“SSL”) secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. Find out more about TLS
Type: Boolean

clientIdClientIdclient_id:client_id

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

useTokenAuthUseTokenAuthuse_token_auth:use_token_auth

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

environmentEnvironment:environment

nullNullNonenil Enables enterprise customers to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our platform customization guide for more details.
Type: String

idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing

false When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
Type: Boolean

fallbackHostsFallbackHostsfallback_hosts:fallback_hosts

[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com] An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host.
When a custom environment is specified, the fallback host functionality is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
Type: String []

transportParamsTransportParamstransport_params:transport_params

Optional. Can be used to pass in arbitrary connection parameters, such as heartbeatInterval and remainPresentFor.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>Map<String, String>

useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol

false If set to true, will enable the binary protocol (MessagePack) if it is supported. It’s disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supportedNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type: Boolean

logExceptionReportingUrl

Defaults to a string value for an Ably error reporting Data Source Name.
Type: String

queryTimeQueryTime:query_timequery_time

false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
Type: Boolean

defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams

When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests
Type: TokenParams

ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions

Channel options are used for setting channel parameters and configuring encryption.

PropertiesMembersAttributes

CipherParamsARTCipherParamsCipherParams HashCipherParams Arrayio.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) or base64-encoded NSString 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 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.StatsRequestParams

TokenParams ObjectARTTokenParamsTokenParams HashTokenParams Arrayio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams

PropertiesMembersAttributesAttributes

capabilityCapability:capability

JSON stringified capability of the Ably Token. If the Ably Token request is successful, the capability of the returned Ably 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 requests for Ably Token from being replayed.
Type: IntegerLong IntegerTimeNSDateDateTimeOffsetDateTime

ttlTtl:ttl

1 hour Requested time to live for the Ably 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