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

Channel Status API

Overview

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, you can check out our Channel Lifecycle Events tutorial, Channel Occupancy Events tutorial, and the Channel Enumeration tutorial.

Channel Status API Reference

Types

The payload of lifecycle 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. This is usually contained within the metrics object, 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

Ready to get started?

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