Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Realtime Client Library API

The Ably Realtime client library establishes and maintains a persistent connection to Ably enabling low latency broadcasting and receiving of messages and presence state. All official client library APIs are consistent across every language offering pub/sub functionality, presence, token and basic authentication, active connection management, symmetric encryption and access to channel, presence and metrics history.

The Ably Realtime client library is available in most popular languages and platforms including Javascript, iOS, Android, Java, .NET, Node.js, Ruby, Go and more…

Download one of our Realtime client libraries now »

Quick intro to the Realtime library

The Realtime library, when instanced, establishes a WebSocket connection to Ably. This WebSocket connection is both multiplexed, allowing multiple channels to share a single connection, and bi-directional, allowing realtime messages to be sent both to and from the Ably service without having to fall back to inefficient techniques like HTTP polling.

Ably organizes realtime data (messages) within applications into named channels that are the “unit” of distribution. A client attaches to a channel to subscribe to messages, and every message published on a channel is broadcast by Ably to all subscribers. This scalable and resilient messaging pattern is commonly called pub/sub.

Data published on a channel is packaged as a message by the library before being sent to the Ably service. The message can contain, in addition to a binary, string or JSON payload, an event name and additional metadata in the extras field.

These concepts are illustrated in the diagram below:


Realtime client diagram

An Ably Realtime client library is responsible for:

Connection state management
Actively managing the WebSocket connection by reconnecting automatically to an available datacenter when a connection drops and restoring the connection state. Find out more about the connection object and its state and connection state recovery which provides message continuity over changing network conditions.
Channel management
Providing publish and subscribe capabilities over channels and actively managing them by queueing published messages when disconnected and retrieving missed messages once reconnected. The library proactively reattaches channels that become suspended due to long periods of disconnectedness.
Presence
Allowing a client to register itself as present on a channel and actively ensuring all members present on a channel are kept in-sync locally. The library proactively restores presence state on suspended channels due to long periods of disconnectedness.
Data interoperabilty
Ensuring messages and their payloads (JSON, strings or binary data) are encoded and decoded in a uniform way to ensure interoperability between all supported platforms.
Encryption
Encrypting payloads with the optional user-generated encryption key ensuring payloads cannot be decrypted whilst in transit or by any party without the private key.

When to use Realtime vs REST libraries

The Realtime library is most commonly used client-side and is stateful, it establishes a connection to Ably for that client and maintains state for the life of the connection. Reasons to use the Realtime library are:

The REST client library is most commonly used server-side i.e. on your application servers, and is stateless. Reasons to use the REST library are:

Other libraries and supported protocols to consider

Diving into the documentation

The Realtime Client Library documentation API is structured as follows:

Step-by-step tutorials

We have a number of tutorials in a wide range of languages to help walk you through some of the key features of our Ably client libraries.
View the Ably tutorials »


Back to top