Client: Presence

Track who’s online in a room, listen for join/leave events, and share ephemeral presence state (like "typing" or "away").

Subscribing

Subscribe to presence in a room:

const { success, present } = await client.subscribePresence(
  "lobby",
  (update) => {
    if (update.type === "join") {
      console.log("User joined:", update.connectionId);
    } else if (update.type === "leave") {
      console.log("User left:", update.connectionId);
    } else if (update.type === "state") {
      console.log("State update:", update.connectionId, update.state);
    }
  }
);

You’ll receive:

• A list of currently present members with metadata via present
• Real-time "join", "leave", and "state" events

The present array includes both connection IDs and their metadata:

// present structure:
[
  { id: "conn_123", metadata: { username: "alice", avatar: "..." } },
  { id: "conn_456", metadata: { username: "bob", avatar: "..." } }
]

Unsubscribe when done:

await client.unsubscribePresence("lobby");

Join + subscribe in one step

Use joinRoom() with a callback to automatically subscribe to presence:

const { success, present } = await client.joinRoom("lobby", (update) => {
  console.log(update);
});

Both subscribePresence() and joinRoom() return the same present format with metadata included.

If you omit the callback from joinRoom(), you still get the current occupants with metadata - but you won’t be subscribed to real-time updates.

Leaving rooms

When you leave a room, any active presence subscription for that room is automatically cleaned up:

await client.leaveRoom("lobby"); // unsubscribes from presence

You don’t need to manually call unsubscribePresence() after leaving a room.

Publishing presence state

Send ephemeral presence state to others in the room:

await client.publishPresenceState("lobby", {
  state: { status: "typing" },
  expireAfter: 8000, // optional (ms)
});

Clear it manually:

await client.clearPresenceState("lobby");

Automatic presence refresh

When the server sends a ping and the client responds with a pong, the server refreshes the presence TTL for all rooms that the client connection has joined.

You don’t need to manually track rooms or re-send updates for each room your client has joined.

Receiving presence states

Presence updates include state events:

const { success, present, states } = await client.subscribePresence(
  "lobby",
  (update) => {
    if (update.type === "state") {
      console.log(`${update.connectionId} state:`, update.state);
    }
  }
);

You’ll also get a states object with current values at the time of subscription:

{
  "abc123": { status: "typing" },
  "def456": { status: "away" }
}

Working with member metadata

Both methods return member information including metadata:

const { success, present } = await client.subscribePresence("lobby", callback);
// or
const { success, present } = await client.joinRoom("lobby");
 
// Display current members
present.forEach(member => {
  console.log(`${member.metadata?.username || member.id} is online`);
});

For real-time updates in your presence callback, resolve metadata for new connections:

await client.subscribePresence("lobby", async (update) => {
  if (update.type === "join") {
    const metadata = await client.getConnectionMetadata(update.connectionId);
    console.log(`${metadata?.username || update.connectionId} joined`);
  }
});

Use cases

• Online indicators with user names and avatars
• Room occupancy lists
• Typing indicators
• Game states like “ready”, “spectating”, etc.

Tips

• Both joinRoom() and subscribePresence() include member metadata automatically
• Unsubscribe when no longer needed to reduce overhead
• Resubscribe after reconnecting (or use createPresence, which handles this for you)
• Use expireAfter for short-lived states like "typing"
• Debounce frequent updates to avoid spamming the network