SSE and Raw HTTP Streaming API

Server-sent events

Copied!

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 version of the API is 1.2, so v=1.2 is recommended.
separator: optional. A separator, to enable easy subscriptions to channels with commas in their name. For example, ?separator=|&channel=fo,o|ba,r will subscribe to the two channels fo,o and ba,r.
key: optional. An Ably API key to use, if using basic auth.
accessToken: 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

Copied!

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

Select...

var apiKey = '<loading API key, please wait>';
var url = 'https://realtime.ably.io/event-stream?channels=myChannel&v=1.2&key=' + apiKey;
var eventSource = new EventSource(url);


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

API Key:Demo Only
Copy
Copied!


curl "https://rest.ably.io/sse?channel=example&v=1.2" \
  --user "<loading API key, please wait>"
⏎
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"
}

API Key:Demo Only
Copy
Copied!

Plain HTTP event stream

Copied!

GET realtime.ably.io/event-stream

Starts a streaming HTTP request. This allows for messages to be easily consumed with any HTTP library that supports streaming. This is similar to the SSE endpoint, but uses JSON envelopes instead of SSE events.

When available, we recommend using an SSE library as opposed to the 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 version of the API is 1.2, so v=1.2 is recommended.
separator: optional. A separator, to enable easy subscriptions to channels with commas in their name. For example, ?separator=|&channel=fo,o|ba,r will subscribe to the two channels fo,o and ba,r.
key: optional. An Ably API key to use, if using basic auth.
accessToken: optional An Ably auth token to use, if using token auth.
lastEvent: optional. An id to resume from. Only required when starting a new HTTP 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

Copied!

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>
}
Copy
Copied!

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.2" \
  --user "<loading API key, please wait>"


{
  "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"
  }
}

API Key:Demo Only
Copy
Copied!

Select...

const request = require('request');
const apiKey = '<loading API key, please wait>';
const url = 'https://realtime.ably.io/event-stream?channels=myChannel&v=1.2&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 Key:Demo Only
Copy
Copied!