Channel options overview

Channel options can be used to customize the functionality of channels. This includes enabling features such as encryption and deltas, or for a client to retrieve messages published prior to it attaching to a channel using rewind.

Channel options are set under the following properties:

• Params
• Modes
• Cipher

Set channel options

Channel options can be set in two different ways:

• When a channel instance is first obtained using channels.get().
• Using channel.setOptions() at any point after the channel instance has been obtained.

channels.get

Pass a channelOptions object into the call to get() in order to set the desired channel options when obtaining a channel instance.

The following is an example of setting the cipher property to set encryption when obtaining a channel instance:

const realtime = new Ably.Realtime('demokey:*****');
const cipherKey = await realtime.Crypto.generateRandomKey();
const channel = realtime.channels.get('far-bot-pad', {cipher: {key: cipherKey}});

channel.setOptions

You can modify the channelOptions associated with a given channel instance by calling setOptions() and passing a new channelOptions object. The modified options will either take effect at the time of attachment, if an attach for that channel has not yet been initiated, or the setOptions() call will trigger an immediate attach operation to apply the modified options. Success or failure of any triggered attach operation is indicated in the result of the setOptions() call.

The following is an example of setting the rewind property to 15 seconds using setOptions():

const realtime = new Ably.Realtime('demokey:*****');
const channelOpts = {params: {rewind: '15s'}}
await channel.setOptions(channelOpts);

Params

The params property can be used to enable additional features on a channel-by-channel basis.

Rewind

The rewind feature enables clients to replay messages that were published to the channel prior to that clients attachment. This can be by a specific number of messages, or a by a period of time.

Delta

The delta feature enables clients to subscribe to a channel so that message payloads only contain the difference, or delta, between the current and previous message.

Occupancy

Occupancy provides metrics about the clients attached to a channel, such as the number of connections and the number of clients subscribed to the channel. occupancy can be specified in the params property in order to subscribe a client to occupancy metrics for the channel. The metrics will be received by a client as events on the channel.

As occupancy requires a channel subscription, it is only available when using the realtime interface of an Ably SDK.

Subscribe to occupancy events

The value of the occupancy property can be set depending on the metrics you want to subscribe to:

Occupancy metrics have an event name of [meta]occupancy which can be used to subscribe to that event type when registering a listener.

The following example shows how to subscribe to all occupancy metrics:

const channelOpts = { params: { occupancy: 'metrics' } };
const channel = ably.channels.get('far-bot-pad', channelOpts);

await channel.subscribe('[meta]occupancy', (message) => {
  console.log('occupancy: ', message.data);
});

The following example shows how to subscribe to only subscriber metrics:

const channelOpts = { params: { occupancy: 'metrics.subscribers' } };
const channel = ably.channels.get('far-bot-pad', channelOpts);

await channel.subscribe('[meta]occupancy', (message) => {
  console.log('occupancy: ', message.data);
});

The following is an example of an occupancy metric event:

{
  "name": "[meta]occupancy",
  "id": "V12G5ABc_M:0:0",
  "timestamp": 1612286351217,
  "clientId": null,
  "connectionId": null,
  "connectionKey": null,
  "data": {
    "metrics": {
      "connections": 1,
      "publishers": 1,
      "subscribers": 1,
      "presenceConnections": 1,
      "presenceMembers": 0,
      "presenceSubscribers": 1,
      "objectPublishers": 1,
      "objectSubscribers": 1
    }
  },
  "encoding": null,
  "extras": null,
  "size": null
}

Occupancy events have a payload in the data property with a value of occupancy. If a client only subscribes to a single metric category, then only that member is present. For example if only subscribing to the publishers category:

{
  "name": "[meta]occupancy",
  "data": {
    "metrics": {
      "publishers": 2
    }
  }
}

Inband Objects

Inband objects allows clients to subscribe to changes to LiveObjects channel objects as regular channel messages.

When using inband objects, the client receives messages with the special name [meta]objects that describe the current set of objects on a channel.

For more information see the inband objects documentation.

Modes

Channel mode flags enable a client to specify which functionality they will use on the channel.

A client can explicitly request a set of modes using the modes property. If the modes property is not provided, the default modes will be used.

The available set of channel mode flags are:

The set of modes available to a client is determined by the set of capabilities granted by their token or API key.

The modes granted by each capability are:

The actual modes assigned to a client will be the intersection of the requested modes and the modes available to the client according to its capabilities. For example, a client with the subscribe capability which explicitly requests SUBSCRIBE and PUBLISH modes will be assigned only the SUBSCRIBE mode.

The following is an example of setting channel mode flags:

const realtime = new Ably.Realtime('demokey:*****');
const channelOptions = {
  modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('far-bot-pad', channelOptions);

A common use case for channel mode flags is to provide clients the ability to be present on a channel, without subscribing to presence events.

The following example demonstrates this use case, where the client would be present on the channel without receiving presence notifications from other clients in the presence set. As this is server-side filtering, clients won't be receiving presence notifications which saves a potentially high volume of messages from being used.

const realtime = new Ably.Realtime('demokey:*****');
const channelOptions = {
  modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('far-bot-pad', channelOptions);

Cipher

The cipher property can be used to enable message encryption. This ensures that message payloads are opaque and can only only be decrypted by other clients that share your secret key.

Channel options without Ably SDK support

For any Ably SDKs that do not currently expose the channel options API, a set of channel options 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.

To specify the channel option 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 SDK means that channel options are specified for the lifetime of the Channel instance. In order to reference the same channel, but with different options, it is necessary to get a new Channel instance, using a qualified name that includes the new channel options.

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

const realtime = new Ably.Realtime('demokey:*****');
const channel = realtime.channels.get('[?rewind=1]far-bot-pad');