Channels

Ably Platform organizes the message traffic within applications into named channels. Channels are the medium through which messages are distributed; clients attach to channels to subscribe to messages, and every message published to a unique channel is broadcast by Ably to all subscribers. This scalable and resilient messaging pattern is commonly called pub/sub.

The Ably REST client library provides a straightforward API for publishing messages and retrieving message history from a channel.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETObjective-CSwift
JavaScript

var rest = new Ably.Rest('<loading API key, please wait>');
var channel = rest.channels.get('ray-map-ash');
channel.publish('example', 'message data', function() {
  channel.history(function(err, resultPage) {
    console.log('Last published message:' + resultPage.items[0]);
  });
});

API Key:
Demo Only
Copy
Copied!

If you would prefer to just dive into code and see some examples of how to use channels, then we recommend you take a look at our REST tutorials.

In order to publish, retrieve message history or access presence history, you must first obtain a REST channel instance.

A Channel object is a reference to a single channel. A channel instance is obtained from the channels collection of the Rest instance, and is uniquely identified by its unicode string name. Find out more about channel naming

JavaScriptNode.jsJavaC# .NETRubyPythonPHPObjective-CSwift
JavaScript
var channel = rest.channels.get('channelName');
Copy
Copied!

To find out more about subscribing to messages published on channels in realtime, see the Realtime channel API.

A set of channel options may also be passed to configure a channel for encryption. Find out more about symmetric message encryption.

JavaScriptNode.jsJavaC# .NETRubyPythonPHPObjective-CSwift
JavaScript
Crypto.generateRandomKey(function(err, key) {
  var options = { cipher: { key: key } };
  var channel = rest.channels.get('channelName', options);
});
Copy
Copied!

Ably provides a REST API to query your app for metadata about channels, as well as a realtime API to subscribe to channel lifecycle events. Using the REST API, you can enumerate all active channels, or obtain the status of an individual channel. Using our Realtime API, you can subscribe to channel lifecycle events (such as being created or closed etc), or subscribe to periodic occupancy updates for all active channels (such as how many people are subscribed to a channel).

One or more channel rules may be configured for an app in your dashboard. These are rules which apply to a channel based on its ‘namespace’. The namespace is the first colon-delimited segment of its name (from the start, up to and including, the last character before the :). If the channel name contains no colon, the namespace is the entire channel name.

For example, the following channels are all part of the “public” namespace:

• public
• public:events
• public:news:americas

Note that wildcards are not supported in channel namespaces.

The namespace attributes that can be configured are:

Persist last message

if enabled, the very last message published on a channel will be stored for an entire year, retrievable using the channel rewind mechanism by attaching to the channel with rewind=1. If you send multiple messages atomically in a single protocol message, for example with publish([{...}, {...}, {...}]), you would receive all of them as one message. Only messages are stored, not presence messages. This last message storage is not accessible using the normal history API, only through rewind. Please note that for the message stored, an additional message is deducted from your monthly allocation.

Persist all messages

if enabled, all messages within this namespace will be stored according to the storage rules for your account (24 hours for free accounts). You can access stored messages via the history API. Please note that for each message stored, an additional message is deducted from your monthly allocation.

Identified

if enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are identified (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about authenticated and identified clients.

TLS only

if enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably’s client libraries use TLS when communicating with Ably over REST or when using our Realtime transports such as Websockets.

Push notifications enabled

If checked, publishing messages with a push payload in the extras field is permitted and can trigger the delivery of a push notification to registered devices for the channel. Find out more about push notifications.

Message interactions enabled

If enabled, messages received on a channel will contain a unique timeserial that can be referenced by later messages for use with message interactions. Find out more about message interactions.

Key or token capabilities can also specify access rights based on channel namespace. Find out more about authentication.

Channels expose a presence member which a client can use to obtain present members and presence event history for the channel itself. See the REST presence documentation for details.

View the Channels and Channel API Reference.