Querying channel state

Three server-side reads answer three questions: which channels are occupied right now, whether anyone is on one particular channel, and who is present on a presence channel. All three authenticate the same way as publishing, with your Bird API key plus the app's own key and secret.

Ejemplo de código

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

Ejemplo de código

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

for (const channel of data) {
  console.log(channel.name);
}

A channel is listed when at least one connection is subscribed to it, and occupancy is the only thing "listed" can mean: channels are never created or registered, so a channel nobody is subscribed to does not exist to be reported. prefix narrows the answer to one family of names, which is how you ask "which rooms have people in them" (presence-) or "which orders is anybody watching" (orders-).

The listing is not paginated. Every occupied channel comes back in one response and there is no cursor to follow, because this is a live snapshot rather than a collection you page through. See list channels.

Whether one channel has anybody on it

Ejemplo de código

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

if (!channel.occupied) return; // nobody is listening; skip the work

A name you have never used is not an error here. It resolves with occupied: false, so this read is safe to make for any channel name your code can construct. It is the cheap guard in front of expensive work: skip the report generation, the third-party fetch, or the diff computation when there is no one subscribed to receive the result. See get a 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.

Anything else is a validation error (400), and so is a count that cannot apply: member_count on a non-presence channel, member_count on list without a presence prefix, or connection_count while the app's flag is off.

Requesting attributes counts as one extra message toward usage. Ask for the counts you are going to use, and skip them when occupancy alone answers your question.

The two counts differ in a way worth keeping straight: one member can hold several connections, so 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 why.

Who is present

Ejemplo de código

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

for (const member of members) {
  console.log(member.member_id);
}

Member ids, and only member ids. The member_info your authorization endpoint attaches travels to subscribed clients over the realtime connection and is not available over REST, so pair the ids with your own user records to render names or avatars. See list channel members.

Reading state while you publish

When you are publishing anyway, include on the publish call returns the same counts for every target channel, which is cheaper than a separate read and tells you what the channel looked like at the moment the event went out. See Reading channel state as you publish.

These are point-in-time reads

Every answer here was true when the request ran and may be false a second later. That is fine for a decision you make once ("is anyone listening before I do this work?", "who is in this room right now?"). It is a poor way to follow state over time: polling list on a timer is a wide, repeated read that tells you less than the events Bird will send you unprompted.

For continuous state, subscribe an endpoint to the realtime webhook groups instead. realtime.channel_existence fires as channels become occupied and vacated, realtime.presence as members join and leave, and realtime.connection_count as a channel's connection count changes. Your server then keeps its own view up to date, and these reads become what they are good at: the one-off check, and reconciling after a gap.

Next steps

Publishing events covers publishing, batching, and the include shortcut.
Presence channels explains members, connections, and member_info.
Realtime overview explains apps, keys, and where usage shows up.