Channel Parameters

Ably provides channel parameters as a means of customizing channel functionality. For example, you can request that a channel attachment start from some time in the past by using the rewind parameter.

The methods provided for specifying channel parameters are outlined below.

A set of channel parameters is a set of key/value pairs, where both keys and values are strings; the keys correspond to specific features that Ably defines:

rewind

Allows an attachment to a channel to start from a given number of messages or point in time in the past. See rewind for more information.

delta

Enables delta compression, a way for a client to subscribe to a channel so that message payloads sent contain only the difference (ie the delta) between the present message and the previous message on the channel. See deltas for more information.

You can specify channel parameters in the ChannelOptions when obtaining a Channel. A collection of channel parameters is expressed as a map of string key/value pairs. The ChannelOptions associated with a channel may also be updated by calling setOptions. The parameters associated with a channel take effect when the channel is first attached; if the parameters are subsequently modified via a call to setOptions, then that call triggers an attach operation that applies the updated parameters, if successful.

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

JavaScriptNode.jsJavaSwiftC# .NET
JavaScript

var realtime = new Ably.Realtime('<loading API key, please wait>');
var channelOpts = {params: {rewind: '1'}};
var channel = realtime.channels.get('ray-map-ash', channelOpts);

API Key:
Demo Only
Copy
Copied!

To modify the rewind channel parameters with the value "15s":

JavaScriptNode.jsJavaSwiftC# .NET
JavaScript

var realtime = new Ably.Realtime('<loading API key, please wait>');
var channelOpts = {params: {rewind: '15s'}}
channel.setOptions(channelOpts, (err) => {
  if(!err) {
    console.log('channel params updated');
  }
});

API Key:
Demo Only
Copy
Copied!

For the client libraries that do not currently expose the API, or transports that do not involve using an Ably library, a set of channel parameters can be expressed by including a query string with 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.

Examples of transports that do not use Ably libraries include using SSE without any library, or using a supported non-Ably protocol such as MQTT

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 a non-supported 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.

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

const realtime = new Ably.Realtime('<loading API key, please wait>');
const channel = realtime.channels.get('[?rewind=1]ray-map-ash');

API Key:
Demo Only
Copy
Copied!

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.

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

var querystring = 'v=1.2&channels=ray-map-ash&rewind=1&key=<loading API key, please wait>';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

API Key:
Demo Only
Copy
Copied!

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.2&key=<loading API key, please wait>&channels=' + channels';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

API Key:
Demo Only
Copy
Copied!

• Request that an attachment start from a given number of messages or point in time in the past using rewind.
• Request that data payloads should be sent as deltas to the previous payload using deltas.

View the Channel Options API Reference.