Optional authA 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 is set on the XHR request.
Optional authThe HTTP verb to use for any request made to the authUrl, either GET or POST. The default value is GET.
HTTPMethods.GET
Optional authA 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 requires these to be added to validate the request or implement the response.
Optional authA URL that the library may use to obtain a token string (in plain text format), or a signed TokenRequest or TokenDetails (in JSON format) from.
Optional autoWhen true, the client connects to Ably as soon as it is instantiated. You can set this to false and explicitly connect to Ably using the connect() method. The default is true.
true
Optional clientA client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string, except it cannot contain a *. 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.
Optional closeWhen 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 (that is, 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. Defaults to true.
Optional connectivityOverride the URL used by the realtime client to check if the internet is available.
In the event of a failure to connect to the primary endpoint, the client will send a GET request to this URL to check if the internet is available. If this request returns a success response the client will attempt to connect to a fallback host.
Optional defaultWhen a TokenParams object is provided, it overrides the client library defaults when issuing new Ably Tokens or Ably TokenRequests.
Optional disableDisable the check used by the realtime client to check if the internet is available before connecting to a fallback host.
Optional disconnectedIf the connection is still in the DISCONNECTED state after this delay in milliseconds, the client library will attempt to reconnect automatically. The default is 15 seconds.
15s
Optional echoIf false, prevents messages originating from this connection being echoed back on the same connection. The default is true.
true
Optional environment
Enables a custom environment to be used with the Ably service.
Optional fallbackAn array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. If you have been provided a set of custom fallback hosts by Ably, please specify them here.
`['a.ably-realtime.com', 'b.ably-realtime.com', 'c.ably-realtime.com', 'd.ably-realtime.com', 'e.ably-realtime.com']``
Optional fallbackThis property is deprecated and will be removed in a future version. Enables default fallback hosts to be used.
Optional httpThe maximum number of fallback hosts to use as a fallback when an HTTP request to the primary host is unreachable or indicates that it is unserviceable. The default value is 3.
3
Optional httpThe maximum elapsed time in milliseconds in which fallback host retries for HTTP requests will be attempted. The default is 15 seconds.
15s
Optional httpTimeout in milliseconds for opening a connection to Ably to initiate an HTTP request. The default is 4 seconds.
4s
Optional httpTimeout in milliseconds for a client performing a complete HTTP request to Ably, including the connection phase. The default is 10 seconds.
10s
Optional idempotentWhen 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. The default is true.
true
Optional key
The full API key string, as obtained from the Ably 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.
Optional log
Parameters to control the log output of the library, such as the log handler and log level.
This property is deprecated and will be removed in a future version. Use the logLevel and logHandler client options instead.
Optional logControls the log output of the library. This is a function to handle each line of log output. If you do not set this value, then console.log will be used.
The log message emitted by the library.
Optional logControls the verbosity of the logs output from 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).
Optional maxThe maximum message size is an attribute of an Ably account which represents the largest permitted payload size of a single message or set of messages published in a single operation. Publish requests whose payload exceeds this limit are rejected by the server. maxMessageSize enables the client to enforce, or further restrict, the maximum size of a single message or set of messages published via REST. The default value is 65536 (64 KiB). In the case of a realtime connection, the server may indicate the associated maximum message size on connection establishment; this value takes precedence over the client's default maxMessageSize.
65536
Optional plugins
A map between a plugin type and a plugin object.
Optional vcdiff?: any
A plugin capable of decoding vcdiff-encoded messages. For more information on how to configure a channel to use delta encoding, see the documentation for the @ably-forks/vcdiff-decoder package.
Optional port
Enables a non-default Ably port to be specified. For development environments only. The default value is 80.
80
Optional queryIf true, the library queries 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. The default is false.
false
Optional queueIf false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior enables applications to submit messages immediately upon instantiating 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. The default is true.
true
Optional realtimeEnables a non-default Ably host to be specified for realtime connections. For development environments only. The default value is realtime.ably.io.
"realtime.ably.io"
Optional realtimeTimeout for the wait of acknowledgement for operations performed via a realtime connection, before the client library considers a request failed and triggers a failure condition. Operations include establishing a connection with Ably, or sending a HEARTBEAT, CONNECT, ATTACH, DETACH or CLOSE request. It is the equivalent of httpRequestTimeout but for realtime operations, rather than REST. The default is 10 seconds.
10s
Optional recover
Enables 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.
Optional restSet of configurable options to set on the HTTP(S) agent used for REST requests.
See the NodeJS docs for descriptions of these options.
Optional keepSee NodeJS docs
Optional maxSee NodeJS docs
Optional restEnables a non-default Ably host to be specified. For development environments only. The default value is rest.ably.io.
"rest.ably.io"
Optional suspendedOptional tls
When false, the client will use an insecure connection. The default is true, meaning a TLS connection will be used to connect to Ably.
true
Optional tlsEnables a non-default Ably TLS port to be specified. For development environments only. The default value is 443.
443
Optional token
An authenticated token. This can either be a TokenDetails object or token string (obtained from the token 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 enables the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Read more about Token authentication.
Optional tokenAn 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 enables 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.
Optional transportA set of key-value pairs that can be used to pass in arbitrary connection parameters, such as heartbeatInterval or remainPresentFor.
Optional transports
An array of transports to use, in descending order of preference. In the browser environment the available transports are: web_socket, xhr, and jsonp.
Optional useWhen true, the more efficient MsgPack binary encoding is used. When false, JSON text encoding is used. The default is true for Node.js, and false for all other platforms.
true for Node.js, false for all other platforms
Optional useWhen true, forces token authentication to be used by the library. If a clientId is not specified in the ClientOptions or TokenParams, then the Ably Token issued is anonymous.
Optional authCalled 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 the authentication documentation for details of the Ably TokenRequest format and associated API calls.
The parameters that should be used to generate the token.
A function which, upon success, the authCallback should call with one of: an Ably Token string (in plain text format); a signed TokenRequest; a TokenDetails (in JSON format); an Ably JWT. Upon failure, the authCallback should call this function with information about the error.
A function which, upon success, the authCallback should call with one of: an Ably Token string (in plain text format); a signed TokenRequest; a TokenDetails (in JSON format); an Ably JWT. Upon failure, the authCallback should call this function with information about the error.
Should be null if the auth request completed successfully, or containing details of the error if not.
A valid TokenRequest, TokenDetails or Ably JWT to be used for authentication.
Generated using TypeDoc
Passes additional client-specific properties to the REST
constructor()or the Realtimeconstructor().