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
string
required
One or more channel names, separated by commas. Non-URL-safe characters should be URL-encoded.Example:
channels=channel1,channel2string
required
API version. Use
v=1.2 for the current version.string
Your Ably API key for Basic authentication.
string
An Ably auth token for Token authentication.
string
Event ID to resume from when reconnecting.
integer
Number of recent messages to retrieve on connection. Maximum 100.Example:
rewind=10 retrieves the last 10 messages.boolean
default:"true"
If
true, message data is wrapped in a Message object. If false, returns raw message payload.boolean
default:"false"
If
true, sends explicit heartbeat events. If false, uses newlines as keepalive.string
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:event
A message published to the channel.
event
A presence event on the channel.
event
An error occurred (for example, token expired).
event
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