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.
Getting started
The Ably REST client library provides a straightforward API for publishing messages and retrieving message history from a channel.
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]);
});
});
Demo OnlyCopyCopied!
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.
Channels
In order to publish, retrieve message history or access presence history, you must first obtain a REST channel instance.
Obtaining a 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
var channel = rest.channels.get('channelName');
CopyCopied!
To find out more about subscribing to messages published on channels in realtime, see the Realtime channel API.
Setting channel options and encryption
A set of channel options may also be passed to configure a channel for encryption. Find out more about symmetric message encryption.
Crypto.generateRandomKey(function(err, key) {
var options = { cipher: { key: key } };
var channel = rest.channels.get('channelName', options);
});
CopyCopied!
Channel metadata
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).
Channel namespaces
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.
Presence
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.
API Reference
View the Channels and Channel API Reference.