Warning: You are viewing an old version (1.1) of this documentation. We recommend you view the latest version 1.2.
Realtime Client Library API

Channel Metadata API


The Channel Metadata API allows for information about channels, such as the current state changes of a channel, or the changes in its occupancy, to be accessed. This is enabled through three primary mechanisms:

  • Channel lifecycle events are triggered when a channel changes its lifecycle state.
  • Channel Occupancy events are sent periodically whenever there is a change in the occupancy of a channel, indicating how many of each type of occupant i.e. publishers, subscribers, presence members or connections there are.
  • The Channel Status API allows for users to query a one-off request with regards to status and occupancy data of channels using a REST query. In addition to that, it also allows you enumerate all the active channels in a particular app. The details of the Channel Status API are covered in out REST library documentation.

In addition, note that since the metadata of various channels is prone to change very frequently, unless you have a special use case within your app, we recommend you to subscribe to the realtime events via the Channel Metadata API rather than poll for updates via REST, as this is inefficient and data is still likely to become stale as soon as you have received it.


Metachannels are a namespace of channels which all start with the [meta] qualifier, uniquely identifying them from regular channels. An example of a metachannel would be [meta]channel.lifecycle.

There are a number of metachannels available, which are:

This metachannel is used to broadcast log messages (usually error messages) for events that occur within the application’s context
This metachannel carries messages about channel lifecycle and metadata
This metachannel carries messages about the lifecycle of realtime connections

All of the metadata associated with an app or a channel is available on one of these metachannels only.


A regular Ably key has a capability which lists available resources and, for any given resource, a set of permitted operations. The wildcard resource ‘*’ will match any regular channel name.

In order to grant permission to a user to access a metachannel, however, the resource name(s) in the capability must include the [meta] qualifier explicitly. If you are using an API Key, you can set up capabilities in your dashboard.

If you are making use of tokens, you specify it within the token. The following are examples of capabilities that will validly permit access to a metachannel with tokens:

A capability allowing subscription to all metachannels:


The above will allow for the key to subscribe to any meta channel. The wildcard * indicates anything can follow the [meta] claim, so an example of a valid channel would be [meta]log. However, this capability will not allow for any other actions to be performed on the metachannels, nor will it allow the key to do anything with any non-metachannels.

A capability allowing all permissible actions on all metachannels and all regular channels:


The above permission provides two capabilities; the ability to perform any action on any metachannel (such as [meta]log) with "[meta]*":["*"], and the ability to perform any action on any channel (such as another:channel) with "*":["*"]. However, you are never able to publish or be present in a metachannel, thus this permission in effect would result in an actual permission excluding publish and presence capabilities in [meta] channels due to the intersecting capabilities.

If [meta] is not specified in the permissions, you will be unable to access the metachannels however. An example of this would be the following:


Although the above provide all capabilities in all regular channel, without a [meta] permission being explicitly specified, you will be unable to perform any actions on a [meta] channel.

Subscribing to realtime events via the Channel Metadata API

Both the channel lifecycle and the occupancy events are published onto a special channel referred to as a metachannel bearing the name [meta]channel.lifecycle, that can be subscribed to with our realtime libraries. This is often used in conjunction with the Ably Reactor, which allows you to send this data to your serverless endpoints, queues, and streams.

Lifecycle Events

The following events arise as messages on the [meta]channel.lifecycle channel. In all cases, the data member of the message is a ChannelDetails instance.

indicates that the channel has been activated globally; that is, it has become active in at least one region, having previously been inactive. The included ChannelDetails.status includes occupancy globally
indicates that the channel has been deactivated globally
indicates that the channel has been activated in a specific region. The included ChannelDetails.status includes occupancy in that region
indicates that the channel has been deactivated in a specific region. The included ChannelDetails.status includes occupancy in that region
indicates a change in global occupancy on the channel. Not all occupancy changes are sent; there is a minimum interval on a per-channel basis, so if the occupancy is changing continuously, then only periodic snapshots of occupancy are sent. Further roll-up of events may occur depending on the capacity of the lifecycle channel. Any occupancy changes in which any of the occupancy categories changes from 0 to a non-zero count, or vice versa, are always included. This feature is only available to our enterprise customers.

channel.occupancy lifecycle events

When channel.occupancy events are enabled for your app, you can subscribe to channel occupancy events by attaching to the channel [meta]channel.lifecycle using a realtime connection. However, please bear in mind that realtime connections and channels have rate limits based on your package size. If the rate of channel lifecycle events exceeds this, a realtime connection is not going to be a reliable way to consume these events as you may get disconnected or lifecycle events may be discarded.

If you wish to stream this data beyond the limit of a single subscriber connection, you can make use of Ably Reactor with a Reactor rule. This allows you to react to lifecycle events and trigger serverless functions, deliver messages to queues, or stream data to third party services for realtime processing.

Reactor rules

You can associate Reactor rules with metachannels in the same way as for regular channels; configure these using the Message source and use a channelFilter of, for example, ^\[meta\]log. Normally the channelFilter regex will only match normal, non-meta channels; however, a regex of the form ^\[qualifier\]pattern is special-cased to match channels with that qualifier. The pattern is a regex as normal.

If you want webhooks for channel lifecycle events, creating a channel lifecycle webhook is an easy alternative to creating a message rule for the [meta]channel.lifecycle metachannel; such webhooks will have simpler POST bodies as the lifecycle events won’t be wrapped in Message objects.

Use cases

Having access to channel metadata can provide numerous benefits. In a scenario where the number of subscribers of a channel goes well beyond a hundred, usage of other options such as presence becomes less effective leading to an unexpected n-squared problem if all of the clients are subscribed to presence. You could instead make use of our channel metadata to check the number of active subscribers.

Equally, you may want to publish your data only if there is a subscriber for that data. The channel lifecycle events can notify you when a channel is opened, becomes active, or is no longer active thus giving your publisher clients an opportunity to know when the last subscriber leaves the channel.

If you need to be able to query channel metadata at any point, you can make use of the Channel Status API to inspect the state of individual channels, or enumerate all active channels in an app.


If you wish to see an example of how to use channel metadata API, you can check out our Channel Lifecycle Events tutorial, Channel Occupancy Events tutorial, or the Channel Enumeration tutorial.

Channel Metadata API Reference


The payload of metadata events for channels is the ChannelDetails type which contains the channelId and other static information about the channel, plus a status containing a ChannelStatus instance which contains information about the current state of the channel.


ChannelDetails is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.

the required name of the channel including any qualifier, if any
Type: string
in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type: string
in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel
Type: boolean
an optional ChannelStatus instance
Type: ChannelStatus

The following is an example of a ChannelDetails JSON object:

  "channelId": "foo",
  "status": {
    "isActive": true,
    "occupancy": {
      "metrics": {
        "connections": 1,
        "publishers": 1,
        "subscribers": 1,
        "presenceConnections": 1,
        "presenceMembers": 0,
        "presenceSubscribers": 1


ChannelStatus is contained within the ChannelDetails object, and optionally contains an Occupancy object.

a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
Type: boolean
an optional Occupancy instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
Type: Occupancy


Occupancy is optionally contained within the above ChannelStatus object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy attribute of the ChannelStatus object. Membership categories include:

the number of connections attached to the channel that are authorised to publish
Type: integer
the number of connections attached that are authorised to subscribe to messages
Type: integer
the number of connections that are authorised to subscribe to presence messages
Type: integer
the number of connections that are authorised to enter members into the presence channel
Type: integer
the number of members currently entered into the presence channel
Type: integer

API reference

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.