SSE and Raw HTTP Streaming API

The Ably SSE and raw HTTP streaming API provides a way to get a realtime stream of events from Ably in circumstances where using a full Ably Realtime client library, or even an MQTT library, is impractical.

HTTP streaming allows for a request from a client to be held by a server, allowing it to push data to the client without further requests. This, much like WebSockets, help avoid the overhead involved in normal HTTP requests. Server-sent events (SSE) provide a thin layer on top of HTTP streaming. A common use of SSE is through the use of the EventSource API in all modern web browsers.

This feature is currently in beta, however is ready for production loads. If you’re interested in using this feature, or have suggestions on how we can improve it, we would like you to get in touch.

It is subscribe-only: you can not interact with the channel, including to publish, enter presence, query the presence set, attach and detach from channels (without closing and re-opening the stream), or anything else.

Customers who do not want to use a client library on platforms that support SSE, and only require simple subscribe-only streams, may choose to use SSE because it’s an open standard, simple, and requires no SDKs on the client-side. HTTP Streaming may be considered on platforms without an SSE client. However, where possible, we strongly recommend the use of one of our Realtime client libraries, which provide more features and higher reliability, and the full use of our normal realtime messaging API.

Getting Started

SSE is incredibly simple to get started with. The code sample below provides an example of how to use it with Ably.

var key ='xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX';
var url ='https://realtime.ably.io/event-stream?channels=myChannel&v=1.1&key' + key;
var eventSource = new EventSource(url);

eventSource.onmessage = function(event) {
  var message = JSON.parse(event.data);
  console.log('Message: ' + message.name + ' - ' + message.data);
};

Authentication

Typically token authentication should be used, using a token issued from your server using an Ably SDK and an API key. This can then be passed to Ably using a querystring token parameter or an Authorization: Bearer <base64-encoded token> header.

It is possible to use an API key as authentication, however for security reasons that is rarely advisable. If you do wish to use an API key however, you can use a querystring parameter of key or an Authorization: Basic <base64-encoded key> header. See REST API authentication for more information.

Connection state is only retained for two minutes. See Connection state explained for full documentation.

Due to this feature being in beta, it is currently subject to other restrictions. For example, at the moment you can not resume from part-way through a backlog of messages that was being sent as part of a previous resume; you can only resume from a message (so you can’t resume unless you’ve received at least one message on the connection); and you can only resume from the id of a message that was sent in the last two minutes (so it will not work if the last message sent on the connection was more than two minutes ago). We expect to fix all of these by the time this feature graduates out of beta. Get in touch if you’d like more information on when these shortcomings will be fixed in production.

API routes

Server-sent events

GET realtime.ably.io/sse

Start a streaming HTTP request that conforms to the Server-Sent Events spec, for ease of consuming with an SSE library.

The /event-stream endpoint will give an SSE response if the Accept header is set to text/event-stream. The /sse endpoint is also provided as an easier way of forcing an SSE response.

Request parameters
channels
mandatory. One or more channel names, separated by commas (or the separator if specified). Non-url-safe characters should be URL-encoded (for example, ?channels=foo%3Fbar will subscribe to the channel foo?bar). Alias: channel.
v
mandatory. The version of the api you are requesting. The current (and only) version of the API is 1.1, so only v=1.1 is accepted.
separator
optional. A separator, to enable easy subscriptions to channels with commas in their name. For example, ?separator=|&channel=fo,o|ba,r will subcribe to the two channels fo,o and ba,r.
key
optional. An Ably API key to use, if using basic auth.
token
optional An Ably auth token to use, if using token auth.
lastEvent
optional. An id to resume from. Only required when starting a new SSE connection which resumes from a previous connection.
rewind
optional. An integer which, if specified, will send a backlog of the number of messages specified once the connection opens. For example, rewind=1 will give you the most recent message sent on the channel. This is best-effort — only messages from within the last two minutes will be available, and only if the channel has been continuously active since the message was sent; it is not a replacement for the history API. It only has an effect for new connections; when resuming a previous connection using lastEvent, it is ignored in favour of sending you the messages you missed since you were last connected.
enveloped
optional. Default is true. If true, the data from each event envelope for a message event will be a Message object. If false, it will be the payload from the message directly. See Envelope format below.
heartbeats
optional. Default is false. if true will use an explicit heartbeat event rather than a newline as a keepalive packet.
Envelope format

See an example of a plain event stream below, except instead of a JSON object with id, event, data members, you get an SSE event.

Keepalive packets are sent as SSE comments (:keepalive).

Code example
var apiKey = 'xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX';
var url = 'https://realtime.ably.io/event-stream?channels=myChannel&v=1.1&key=' + apikey;
var eventSource = new EventSource(url);

eventSource.onmessage = function(event) {
  var message = JSON.parse(event.data);
  console.log('Message: ' + message.name + " - " + message.data);
};
import json
import sseclient

api_key='xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX'
url = "https://realtime.ably.io/sse?channels=myChannel&v=1.1&key=%s" % (api_key)

def with_urllib3(url):
  import urllib3
  http = urllib3.PoolManager()
  return http.request('GET', url, preload_content=False)

response = with_urllib3(url)
client = sseclient.SSEClient(response)
for event in client.events():
  message = json.loads(event.data)
  print("Channel: %s - Message: %s - %s " % (message['channel'], message['name'], message['data']))
curl "https://rest.ably.io/sse?channel=example&v=1.1" \
  --user "xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX"
⏎
id: cbfKayrzgAXDWM:1556806691343-0
event: message
data: {
  "id":"YqigX7VFsR:0:0",
  "name":"foo",
  "timestamp":1556806691341,
  "encoding":"json",
  "channel":"channel",
  "data":"{\"foo\":1}"
}
⏎
:keepalive
⏎
event: error
data:{
  "message":"Token expired. (See https://help.ably.io/error/40142 for help.)",
  "code":40142,
  "statusCode":401,
  "href":"https://help.ably.io/error/40142"
}

Plain HTTP event stream

GET realtime.ably.io/event-stream

Start a streaming HTTP request, for ease of consuming with any HTTP library that supports streaming. When possible, we recommend using an SSE library as opposed to a raw HTTP stream as SSE libraries automatically handle reconnecting and resuming from the last received ID.

Request parameters
channels
mandatory. One or more channel names, separated by commas (or the separator if specified). Non-url-safe characters should be URL-encoded (for example, ?channels=foo%3Fbar will subscribe to the channel foo?bar). Alias: channel.
v
mandatory. The version of the api you are requesting. The current (and only) version of the API is 1.1, so only v=1.1 is accepted.
separator
optional. A separator, to enable easy subscriptions to channels with commas in their name. For example, ?separator=|&channel=fo,o|ba,r will subcribe to the two channels fo,o and ba,r.
key
optional. An Ably API key to use, if using basic auth.
token
optional An Ably auth token to use, if using token auth.
lastEvent
optional. An id to resume from. Only required when starting a new SSE connection which resumes from a previous connection.
rewind
optional. An integer which, if specified, will send a backlog of the number of messages specified once the connection opens. For example, rewind=1 will give you the most recent message sent on the channel. This is best-effort — only messages from within the last two minutes will be available, and only if the channel has been continuously active since the message was sent; it is not a replacement for the history API. It only has an effect for new connections; when resuming a previous connection using lastEvent, it is ignored in favour of sending you the messages you missed since you were last connected.
enveloped
optional. Default is true. If true, the data from each event envelope for a message event will be a Message object. If false, it will be the payload from the message directly. See Envelope format below.
heartbeats
optional. Default is false. If true will use an explicit heartbeat event rather than a newline as a keepalive packet.
Envelope format

Once a streaming response is established, every line (other than empty lines sent as keepalive packets) will be a simple JSON object of the following form:

{
  event: <string, the event type, such as message, presence, error or heartbeat>,
  data: <message, presence or error object. Not present for heartbeats>,
  id: <string, the ID to use to resume from this point, see connection state
       recovery for details. Only present for message and presence events>
}

If enveloped is true (the default), the data will be a JSON-stringified object of a type determined by the event:

- For a message event it will be a Message object
- For a presence event it will be a PresenceMessage object
- For an error event it will be an ErrorInfo object

For a payload that is anything other than a string, as there is no client library to decode the payload of a Message or PresenceMessage, you will have to decode it yourself. Objects and arrays will be json-encoded; binary payloads will be base64-encoded. The encoding field of the Message will specify what encoding has been used for the data payload.

If enveloped is false, the data will for a message or presence event be the data payload from the Message or PresenceMessage. Other events are unaffected.

Non-string payloads will be encoded as before, but without enveloping you will not have the benefit of the encoding field to tell you what encoding has been done.

Note that failures on opening the connection (for example, invalid authentication details) may be sent as a non-streamed http response (with a response body of the form {"error": <ErrorInfo>}), not an error event in a streamed response.

Code example
curl "https://rest.ably.io/event-stream?channel=example&v=1.1" \
  --user "xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX"

{
  "id":"cbfKayrzgAXDWM:1556804156735-0",
  "event":"message",
  "data":{
    "id":"oZs6XaGYx8:0:0",
    "name":"message-name",
    "timestamp":1556804156730,
    "encoding":"json",
    "channel":"example",
    "data":"{\"foo\":1}"
  }
}
⏎
{
  "event":"error",
  "data":{
    "message":"Token expired. (See https://help.ably.io/error/40142 for help.)",
    "code":40142,
    "statusCode":401,
    "href":"https://help.ably.io/error/40142"
  }
}
const request = require('request');
const apiKey = 'xVLyHw.VyGwgw:jVpi9q5cRfdM9SQX';
const url = 'https://realtime.ably.io/event-stream?channels=myChannel&v=1.1&key=' + apikey;

request
  .get(url)
  .on('response', function(response) {
    console.log(response.statusCode) // stream started, 200
  })
  .on('data', function(data) {
    console.log('Envelope:', data.toString())
  });

API reference
Documentation

Ready to get started?

Our free plan includes 3m messages per month, 100 peak connections, 100 peak channels, and loads of features.