Overview
The SSE API enables you to:- Receive real-time messages over HTTP
- Subscribe to one or more channels
- Use standard SSE libraries and the browser EventSource API
- Automatically reconnect on connection loss
When to Use SSE
The SSE API is ideal for:- Browser applications that need simple real-time updates
- Environments with limited WebSocket support
- Read-only real-time data consumption
- Lightweight integrations
Getting Started
Basic Usage
Connect to the SSE endpoint and subscribe to a channel:Endpoint
The SSE endpoint is:Parameters
One or more channel names, separated by commas. Non-URL-safe characters should be URL-encoded.Example:
channels=channel1,channel2API version. Use
v=1.2 for the current version.Your Ably API key for Basic authentication.
An Ably auth token for Token authentication.
Event ID to resume from when reconnecting.
Number of recent messages to retrieve on connection. Maximum 100.Example:
rewind=10 retrieves the last 10 messages.If
true, message data is wrapped in a Message object. If false, returns raw message payload.If
true, sends explicit heartbeat events. If false, uses newlines as keepalive.Custom separator for channel names (useful when channel names contain commas).Example:
separator=|&channels=ch1|ch2Message Format
Messages are delivered as SSE events:Event Types
The SSE API sends the following event types:A message published to the channel.
A presence event on the channel.
An error occurred (for example, token expired).
Keepalive heartbeat (when
heartbeats=true).Connection Management
Automatic Reconnection
The browser EventSource API automatically reconnects on connection loss. Use thelastEvent parameter to resume from the last received message:
Keepalive
The SSE connection sends keepalive packets to maintain the connection:- By default, newline characters (
\n) are sent - With
heartbeats=true, explicit heartbeat events are sent