Watchlist events

A member who signs in can name the members they want to follow, and the connection is told when any of them comes online or goes offline. That is the whole feature: no channel per relationship, no polling, one list.

Watchlist events ride on member signin. The identity your backend signs at signin may carry a watchlist array of member ids; when the app's watchlist_events setting is on, the connection receives online and offline events for exactly those ids. A member is online while they have at least one signed-in connection: the first connection fires online, closing the last one fires offline, and tabs in between fire nothing, the same counting presence channels use.

Toggle Watchlist events in the app's settings on the Realtime → Apps page, or set watchlist_events to true on the app through the Realtime API. Connections pick the setting up when they connect, so flip it before the clients that rely on it ship.

The watchlist is part of member_data, the JSON string your member auth endpoint signs. Add the ids next to the identity:

{
  "member_id": "u_1",
  "member_info": { "name": "Ada" },
  "watchlist": ["u_2", "u_3"]
}

Because the list is inside the signed identity, your auth endpoint decides who a member may watch: build the array from your own data (their contacts, their team) rather than accepting one the client sends, or any member can watch any other. A watchlist holds up to 100 ids; a longer list is truncated to the first 100 and the connection receives error 4302 naming the ids that were accepted.

The list is captured at signin and holds for the life of the connection. To change it, have your endpoint sign the new list: the client signs in again automatically on every reconnect, so the next connection follows the updated list and receives its current statuses.

Bind on bird.member.watchlist. The current status of the whole list arrives right after signin, so you can paint who is online before anyone changes state:

await bird.signin();

bird.member.watchlist.bind("online", (memberIds) => {
  console.log("online:", memberIds);
});
bird.member.watchlist.bind("offline", (memberIds) => {
  console.log("offline:", memberIds);
});

Each event carries the member ids it applies to. The initial delivery after signin covers the full list, grouped by status; after that, events arrive as members cross between zero and one connections.

Presence channels answer "who is in this room with me": everyone subscribes to the same channel and sees the same member list. A watchlist answers "are the people I care about online anywhere": each member follows their own list, and the people being watched do nothing at all beyond signing in. A buddy list, an agent-availability indicator, or a "your contact just came online" nudge is watchlist work; a shared room roster is presence.