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 »

The Realtime library, when instantiated, 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:

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 interoperability

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.

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:

• You are developing a mobile, desktop or web client that needs to subscribe to messages in real time.
• You want to maintain a persistent connection to Ably, attach to one or more channels, and publish and subscribe to messages.
• Your application needs to register its presence on a channel, or listen for others becoming present in real time.

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:

• Your application server is used to primarily issues tokens for clients and/or publish messages on channels.
• Your application is mostly stateless i.e. you process a request or respond to an event, and then move onto the next request or event without any previous state carrying through.
• Your prefer a synchronous request over an asynchronous request. Note not all REST libraries are synchronous, but where the platform offers a synchronous and asynchronous approach, the REST libraries are more often synchronous.

• If you want to consume realtime data from one or more of your servers, then we recommend you consider using our Ably Queues or Firehose. With Integrations you can consume realtime data in a robust, resilient and scalable way across multiple support protocols. Find out more about Ably Integrations.
• If you want realtime messages or presence events to trigger execution of code on your servers or in a server-less environment (such as AWS Lambda), then you should consider Webhooks.
• If you want to use another realtime protocol such as MQTT or perhaps even one of our competitors’ protocols, you should review the realtime protocols we support with our Protocol Adapters

The Realtime Client Library API documentation is structured as follows:

• Constructor and usage examples
• Connection
• Channels
• Messages
• Presence
• Authentication
• History
• Encryption
• Statistics
• Types

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. Skip to Ably tutorials »