Documentation
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Querying channel state

Three server-side reads list occupied channels, inspect one channel, and list the members of a presence channel. Authenticate each request with your Bird API key and the Realtime app's key and secret.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
  },
});

Which channels are occupied

const { data } = await bird.realtime.channels.list(appId, { prefix: "presence-" });

for (const channel of data) {
  console.log(channel.name);
}
A channel appears in the list while at least one connection is subscribed. Channels are not created or registered separately, so empty channels do not appear. Use prefix to restrict the result to a family such as presence- or orders-.
The response is not paginated and returns every occupied channel in one live snapshot. See List Realtime channels.

Inspect one channel

const channel = await bird.realtime.channels.get(appId, "presence-lobby", {
  include: ["member_count"],
});

if (!channel.occupied) return; // nobody is listening; skip the work
An unknown or unused name returns 200 OK with occupied: false. Use this result to skip work when no connection can receive it. See Get a Realtime channel.

Counts, through include

include is repeatable and accepts exactly two values:
  • member_count is the number of distinct members, and it works on presence channels only.
  • connection_count is the number of connections subscribed to the channel, and it requires the app's connection-counting setting.
Any other value returns 400 Bad Request. The API also returns 400 Bad Request for member_count on a non-presence channel, a list request without a presence prefix, or connection_count when connection counting is disabled.
Requesting attributes counts as one extra message toward usage. Omit them when occupied answers your question.
One member can hold several connections. A room with three people who each have two tabs open reports a member_count of 3 and a connection_count of 6. Presence channels explains the distinction.

Who is present

const { members } = await bird.realtime.channels.members(appId, "presence-lobby");

for (const member of members) {
  console.log(member.member_id);
}
The response contains only member IDs. member_info is delivered to subscribed clients and is not available through this REST operation. Join the IDs with your own records to render names or avatars. See List channel members.

Reading state while you publish

When publishing, use include to return the same counts for every target channel at publish time. See Reading channel state as you publish.

Point-in-time behavior

Each response is a point-in-time snapshot and can become stale immediately. Use it for one-time decisions rather than polling for continuous state.
For continuous state, subscribe an endpoint to the Realtime webhook groups. realtime.channel_existence reports occupied and vacated channels, realtime.presence reports member changes, and realtime.connection_count reports connection-count changes. Use channel-state reads to initialize or reconcile your stored view.

Next steps