Realtime Client Library API

Channel Metadata API

Overview

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

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:

[meta]log
This metachannel is used to broadcast log messages (usually error messages) for events that occur within the application’s context
[meta]channel.lifecycle
This metachannel carries messages about channel lifecycle and metadata
[meta]connection.lifecycle
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.

Permissions

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:

{"[meta]*":["subscribe"]}

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.

{
  "[meta]*":["*"], 
  "*":["*"]
}

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 explicitily specified, you will be unable to peform 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.

channel.opened
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
channel.closed
indicates that the channel has been deactivated globally
channel.region.active
indicates that the channel has been activated in a specific region. The included ChannelDetails.status includes occupancy in that region
channel.region.inactive
indicates that the channel has been deactivated in a specific region. The included ChannelDetails.status includes occupancy in that region
channel.occupancy
indicates a change in global occupancy. 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

It is worth noting that channel.occupancy events are currently only available to our enterprise customers. However, you can still access occupancy data within channel lifecycle events on a free account.

Occupancy Events

You can subscribe to channel occupancy events by attaching to the channel [meta]channel.lifecycle using a realtime connection. However, realtime connections and channels have rate limits, typically 15 per second for free accounts. 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 rate limit, you can make use of Ably Reactor with a Reactor Rule. This allows you to send data to your serverless endpoints, queues, or streams for 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 that matches the metachannel’s name. Please note: the Channel Lifecycle events are not supported with Reactor Webhooks.

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.

Tutorials

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

Types

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

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

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

ChannelDetails.ChannelStatus

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

isActive
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
occupancy
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

ChannelDetails.ChannelStatus.Occupancy

Occupancy is optionally contained within the above ChannelStatus object, and contains information on the occupants of the channel.

metrics
an optional dictionary of membership categories for a realtime channel and their counts. Membership categories include:
– publishers
the number of connections attached to the channel that are authorised to publish
Type: integer
– subscribers
the number of connections attached that are authorised to subscribe to messages
Type: integer
– presenceSubscribers
the number of connections that are authorised to subscribe to presence messages
Type: integer
– presenceConnections
the number of connections that are authorised to enter members into the presence channel
Type: integer
– presenceMembers
the number of members currently entered into the presence channel
Type: integer

API reference
Documentation

Get started now with our free plan

It includes 3m messages per month, 100 peak connections, 100 peak channels, and loads of features.

Create your free account