DOCSEARCHbyAlgolia
Submit Docs

Ably Realtime Platform Documentation

website·Indexed Apr 17, 2026

https://ably.com/docs/

Official documentation for Ably, a highly-scalable serverless WebSocket platform for building realtime digital experiences. Covers architecture, fault tolerance, edge network, and latency. Includes guides for Pub/Sub, data streaming, and handling discontinuity. Details account management, access tokens, API keys, and the Control API. Features SDK references for multiple languages, CLI tools, and AI/LLM integration. Provides configuration for push notifications, queues, and enterprise customization.

Tokens
85.5K
Snippets
286
Records
432
Agent score
50%

What's inside Ably

  1. Ably Cluster Architecture and Four Primary Layers

    Ably runs on AWS EC2 infrastructure with clusters typically spanning 2 to 10 regions. Each regional deployment operates independently, handling its own connections, REST traffic, and channel management. Cross-region message flow is peer-to-peer to eliminate bottlenecks.

    The architecture consists of four primary layers:

    1. Routing Layer: Provides intelligent, latency-optimized routing for client connectivity.
    2. Gossip Layer: Distributes network topology information and facilitates service discovery.
    3. Frontend Layer: Handles REST requests and maintains realtime connections (WebSocket, Comet, SSE).
    4. Core Layer: Performs central message processing for channels.

    Scaling is achieved through intelligent load distribution:

    • Frontend: New instances join the load balancer pool automatically.
    • Core: Uses consistent hashing to distribute channels across core processes, ensuring even load distribution as the cluster scales.

  2. Understand connection multiplexing and browser tab limitations

    Ably SDKs multiplex all channel traffic over a single connection. This maximizes throughput, minimizes bandwidth, and reduces power usage. You can dynamically subscribe/unsubscribe from channels without creating new connections. However, connections cannot be shared between browser tabs due to browser security sandboxing. Each tab with an Ably client counts as a separate connection.

  3. Ably Platform Architecture Overview and Reliability Guarantees

    Ably's platform is a globally distributed infrastructure designed to deliver dependable realtime experiences at scale, serving billions of devices and trillions of messages monthly. The architecture is built on four pillars of dependability: Performance, Integrity, Reliability, and Availability.

    Key Performance Metrics:

    • <30ms round trip latency within a datacenter (99th percentile)
    • <65ms global round trip latency (99th percentile)

    Key Reliability & Availability Guarantees:

    • Exactly-once delivery semantics with guaranteed message ordering.
    • 100% message delivery guarantee via multi-region redundancy.
    • 99.999999% message survivability and 99.99999999% persisted data survivability.
    • Edge network failure resolution by client SDKs within 30 seconds.
    • Automated traffic routing away from datacenter failures in <2 minutes.
    • 99.999% global service availability (approx. 5 minutes 15 seconds downtime/year).
    • 50% global capacity margin for demand surges.

    The system is designed for horizontal scalability with no single point of congestion, ensuring consistent latency and reliability across the global network.

  4. Ably edge network health monitoring and alerting

    Ably continuously monitors the health of all edge network components using active probes and passive analysis of client connection patterns. Automated alerting systems detect anomalies and notify the operations team for proactive intervention. The health monitoring system feeds into automated traffic routing, directing clients away from unhealthy regions or components without manual intervention.

  5. Choose the right Ably product for your real-time use case

    Ably offers a core Pub/Sub product and several higher-level abstractions built on top of it:

    • Ably Pub/Sub: The core flexible API for crafting any real-time experience.
    • Ably Chat: Purpose-built for live chat (rooms, messages, typing indicators, reactions). Ideal for 1:1 chats, agent support, and gaming streams.
    • Ably Spaces: For multiplayer collaboration (cursor positions, element interaction). Ideal for whiteboards, avatar stacks, and shared document editing.
    • Ably LiveObjects: Synchronizes application state with automatic concurrency handling and conflict resolution. Ideal for voting, leaderboards, and multiplayer game state.
    • Ably LiveSync: Synchronizes database changes (PostgreSQL, MongoDB) to frontend clients in real-time.
    • Ably AI Transport: Upgrades AI streams to bi-directional, stateful experiences with resumable token streaming and session management.

  6. Transport protocol selection and optimization

    Ably client libraries automatically select the most efficient transport protocol based on the client's environment. WebSockets are the preferred transport for realtime connections. If WebSockets are unavailable or blocked (e.g., by restrictive corporate firewalls), the system falls back to comet (long-polling HTTP). Connection parameters like heartbeat intervals can be configured to balance reliability with resource efficiency.

  7. Manage regional failures and traffic redirection

    Ably's multi-region architecture allows for regional independence. If a region becomes unavailable due to infrastructure issues, other regions continue to operate normally, preventing local problems from cascading into global outages.

    Traffic Redirection:

    • Client traffic is dynamically redirected between regions based on health and proximity.
    • When a region is determined to be unhealthy or unreachable, traffic is automatically routed to the next closest healthy region.
    • This redirection is transparent to the end user, minimizing disruption during regional failures.

    This design ensures continuous global service even if an entire region is lost.

  8. Subscribe to channel occupancy metrics

    Occupancy provides metrics about clients attached to a channel, such as the number of connections, publishers, and subscribers. To receive these metrics, set the occupancy parameter in the channel options when getting a channel. This feature is only available in the Realtime SDK.

    Clients require the channel-metadata capability to subscribe to occupancy metrics.

    The occupancy value can be set to:

    • metrics: Enables events containing full occupancy details (connections, publishers, subscribers, presence stats). Updates are debounced to 15 seconds unless a mode change occurs.
    • metrics.<category>: Enables events for a specific category (e.g., metrics.subscribers, metrics.publishers).

    Occupancy events are received with the name [meta]occupancy.

    // Subscribe to all occupancy metrics
const channelOpts = { params: { occupancy: 'metrics' } };
const channel = ably.channels.get('your-channel-name', channelOpts);

await channel.subscribe('[meta]occupancy', (message) => {
  console.log('occupancy: ', message.data);
});

// Subscribe to specific category (e.g., subscribers only)
const channelOptsSub = { params: { occupancy: 'metrics.subscribers' } };
const channelSub = ably.channels.get('your-channel-name', channelOptsSub);

await channelSub.subscribe('[meta]occupancy', (message) => {
  console.log('subscribers: ', message.data);
});

  9. Understand Ably's Layer 7 DoS protection with CloudFront WAF

    Ably uses AWS CloudFront Web Application Firewall (WAF) to protect against sophisticated application-layer (Layer 7) attacks. WAF rules identify and block malicious requests based on patterns, suspicious user agents, or anomalous request rates. It can limit request rates per IP, block traffic from specific geographic regions during attacks, and distinguish between legitimate bots (e.g., search crawlers) and malicious bots. This works in conjunction with AWS Shield Advanced for Layer 3/4 volumetric protection.

  10. Understand Ably channel concepts and naming rules

    Channels are the building blocks of Ably realtime applications, used to separate messages into different topics using the publish-subscribe pattern. They serve as the unit of security and scalability. Clients should only be granted capabilities for channels they are authorized to access.

    Channel naming restrictions:

    • Names are case-sensitive.
    • Cannot start with [ or :.
    • Cannot be empty.
    • Cannot contain newline characters.
    • Recommended length is under 2048 characters (older browsers may struggle with longer URLs).

    Channel namespaces allow grouping channels by the first part of the name up to the first colon (:). For example, customer, customer:tracking-id, and customer:order:update all belong to the customer namespace. Namespaces cannot contain the wildcard character *.

  11. Use Ably for AI Transport and Realtime LLM Workloads

    Ably AI Transport is built on the Ably Pub/Sub platform, leveraging its performance guarantees and scaling capabilities. It is designed for scenarios requiring reliable Large Language Model (LLM) token delivery and session resumability. Key use cases include:

    • Multi-turn conversational AI applications
    • AI agent coordination
    • Live steering with human takeover
    • Any scenario where reliable streaming and session continuity are critical

    This solution works with any AI model or framework.

  12. Ably connectivity and protocol support in China

    Ably's global network with over 700 edge locations provides connectivity to users in China. While the service works in China, the national firewall can block access to foreign services without notice. Ably employs specific strategies including partnerships with local providers, alternative routing, and region-specific optimizations to ensure reliability. Customers should be aware that potential firewall changes could impact service availability.