Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Channel Parameters

Overview

Channel parameters are a general mechanism by which a client can express properties of a channel, or of its attachment to a channel. A set of channel parameters is simply a set of key/value pairs, where both keys and values are strings; the keys correspond to specific features that Ably defines.

The methods provided for specifying channel parameters, and the currently available features, are outlined below.

Currently supported channel params

rewind
Used to request that an attachment start from some number of messages or point in time in the past. See rewind for more information
delta
In an experimental state. Used to request that data payloads should be sent as deltas to the previous payload. Contact us for more information and supported values

Using channel params with v1.1 or earlier Ably client libraries

The current Ably libraries, at version 1.1, do not expose an API for expressing channel parameters. This means that it is necessary to specify parameters in a way that is opaque to the library.

A set of params is expressed by including a query string, using standard URL query syntax and encoding, within the qualifier part of a channel name. The qualifier part is in square brackets at the start of the channel name.

For example, to specify the parameter foo with value bar on channel baz, the qualified channel name would be [?foo=bar]baz. If the channel name already has a qualifier, such as [meta]log, then the query string follows the existing qualifier, as in [meta?foo=bar]log.

Using this syntax with the Ably library means that channel parameters are specified for the lifetime of the Channel instance; in order to reference the same channel, but with different channel parameters, it is necessary to get a new Channel instance, using a qualified name that includes the new channel parameters.

Example

For example, to specify the rewind channel param with the value "1":

const realtime = new Ably.Realtime('{{API_KEY}}');
const channel = realtime.channels.get('[?rewind=1]{{RANDOM_CHANNEL_NAME}}');

Using params with non-Ably transports

It is possible to interact with Ably channels using transports that do not involve using an Ably library; for example using SSE without any library, or using a supported non-Ably protocol such as MQTT. In these cases, it is also necessary to use a qualified channel name.

A set of params is expressed by including a query string, using standard URL query syntax and encoding, within the qualifier part of a channel name. The qualifier part is in square brackets at the start of the channel name.

For example, to specify the parameter foo with value bar on channel baz, the qualified channel name would be [?foo=bar]baz. If the channel name already has a qualifier, such as [meta]log, then the query string follows the existing qualifier, as in [meta?foo=bar]log.

In an SSE connection, it is also possible to specify channel parameters as a query string in the connection URL, instead of as a qualifier on an individual channel name. In this case, the given channel parameters apply to all channel attachments associated with that connection.

SSE example

For example, to specify the rewind channel param with the value "1" using a querystring parameter, where it will apply to all channels:

var querystring = 'v=1.1&channels={{RANDOM_CHANNEL_NAME}}&rewind=1&key={{API_KEY}}';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

Or to specify the same parameter but only applying to one channel of two, using a qualified channel name:

var channelOne = encodeURIComponent('[?rewind=1]channel1');
var channelTwo = 'channel2';
var channels = channelOne + ',' + channelTwo;
var querystring = 'v=1.1&key={{API_KEY}}&channels=' + channels';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

Rewind parameter

The rewind channel parameter relates to the initial attachment of a connection to a channel, and expresses the intent to attach to the channel at a position, or a point in time, in the past (that is, effectively “rewinding” the channel for the purposes of the present attachment).

A rewind parameter can express a channel position in terms of a number of messages, or a time interval.

A rewind value that is simply a number n (eg rewind=1) is a request to attach to the channel at a position n messages before the present position. If that attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If fewer than the requested number of messages exists on the channel (including the case that there are no prior messages), then the available messages are sent; this does not constitute an error.

A rewind value can also be a string that is a time interval specifier. Supported specifier values express an integral number of seconds (eg 15s) or minutes (eg 2m). If that attachment is successful, and one or more messages exist on the channel in the given time interval prior to the present time, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If you wish to use a time interval rewind but additionally specify a limit on the number of messages to be returned, you can use the rewindLimit channel param. For example, to request up to 10 messages in a window 5m before the present time, specify a channel parameter string of rewind=5m&rewindLimit=10. If fewer than the requested number of messages exists on the channel in that interval (including the case that there are no messages), then the available messages are sent; this does not constitute an error.

At most 100 messages will be sent in a rewind request. If the number of messages within the specified interval is greater than that limit, then only the most recent messages up to that limit are sent. The attachment succeeds, but truncation of the message backlog is indicated as a non-fatal error in the attachment response.

By default, a maximum of two minutes of channel history is available when attaching. This means that a rewind time specifier of greater than two minutes will only be able to rewind by two minutes. If a channel has persistence enabled, then it is possible to rewind back in time by up to the persistence TTL on the channel.

The channel position expressed by a rewind parameter has an effect only on an initial channel attachment. Any subsequent reattachment of the same channel on the same connection, in order to resume the connection, will attempt to resume with continuity from the point at which the connection dropped. (There are a few exceptions to this: in particular, client libraries earlier than v1.2 that have been disconnected for over two minutes, and all clients when using recover mode ; in both cases the previous attachment state is not preserved).

Any rewind parameter value that cannot be parsed either as a number or a time specifier represents an error, and any attachment request will fail with an error.

Rewind example with an Ably client library

To subscribe to a channel, getting the most recent message if available:

// only with ably-js v1.2 or later; currently in beta
const realtime = new Ably.Realtime('{{API_KEY}}');
realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
  rewind: '1'
}).subscribe(msg => console.log("Received message: ", msg));
// only with ably-js v1.2 or later; currently in beta
const realtime = new Ably.Realtime('{{API_KEY}}');
realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
  rewind: '1'
}).subscribe(msg => console.log("Received message: ", msg));
// with ably-js v1.1 or below
const realtime = new Ably.Realtime('{{API_KEY}}');
const channel = realtime.channels.get('[?rewind=1]{{RANDOM_CHANNEL_NAME}}');
channel.subscribe(msg => console.log("Received message: ", msg));
// with ably-js v1.1 or below
const realtime = new Ably.Realtime('{{API_KEY}}');
const channel = realtime.channels.get('[?rewind=1]{{RANDOM_CHANNEL_NAME}}');
channel.subscribe(msg => console.log("Received message: ", msg));

Rewind example with SSE

To subscribe to a channel, getting the most recent message if available:

var querystring = 'v=1.1&channels={{RANDOM_CHANNEL_NAME}}&rewind=1&key={{API_KEY}}';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

Rewind example with MQTT

var mqtt = require('mqtt');
var options = {
  keepalive: 30,
  username: 'FIRST_HALF_OF_API_KEY',
  password: 'SECOND_HALF_OF_API_KEY',
  port: 8883
};
var client = mqtt.connect('mqtts:mqtt.ably.io', options);
client.on('connect', () => {
  client.subscribe('[?rewind=1]{{RANDOM_CHANNEL_NAME}}');
});
client.on('message', (topic, message) => {
  ...
});

Back to top