Channel options

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

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.

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:

RealtimeREST
JavaScriptNode.jsJavaC# .NETRubyObjective-CSwiftGo
realtime_javascript

const realtime = new Ably.Realtime('<loading API key, please wait>');
const cipherKey = await realtime.Crypto.generateRandomKey();
const channel = realtime.channels.get('oat-boy-fun', {cipher: {key: cipherKey}});

API Key:
Demo Only
Copy
Copied!

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():

Realtime
JavaScriptNode.jsJavaSwiftC# .NETGoFlutter
realtime_javascript

const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOpts = {params: {rewind: '15s'}}
await channel.setOptions(channelOpts);

API Key:
Demo Only
Copy
Copied!

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

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.

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 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.

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

metrics

this enables events containing the full occupancy details in their data payload. Events are sent when the count for any of the included categories changes. Updates that involve mode changes (for example, at least one publisher existing where there were none before) are propagated immediately. Updates that do not involve a mode change are debounced, for no more than 15 seconds.

metrics.<category>

this enables events whose data payload contains an occupancy value containing the occupancy, that is the client count, for only the given category. Events are sent when the count for any of the included categories changes. Updates that involve mode changes (for example, at least one publisher existing where there were none before) are propagated immediately. Updates that do not involve a mode change are debounced, for no more than 15 seconds.

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:

Realtime
JavaScriptGoFlutterJava
realtime_javascript

const channelOpts = { params: { occupancy: 'metrics' } };
const channel = ably.channels.get('oat-boy-fun', channelOpts);


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

Copy
Copied!

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

Realtime
JavaScriptGoFlutterJava
realtime_javascript

const channelOpts = { params: { occupancy: 'metrics.subscribers' } };
const channel = ably.channels.get('oat-boy-fun', channelOpts);


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

Copy
Copied!

The following is an example of an occupancy metric event:

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

Copy
Copied!

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

Copy
Copied!

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.

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:

Realtime
JavaScriptJavaGoFlutter
realtime_javascript

const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOptions = {
  modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('oat-boy-fun', channelOptions);

API Key:
Demo Only
Copy
Copied!

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.

Realtime
JavaScriptJavaGoFlutter
realtime_javascript

const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOptions = {
  modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('oat-boy-fun', channelOptions);

API Key:
Demo Only
Copy
Copied!

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.

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":

Realtime
JavaScriptJavaPythonGoFlutter
realtime_javascript

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

API Key:
Demo Only
Copy
Copied!