List Users

When connecting with { list: true }, your initial join event includes a users array of everyone currently announced on the channel. From there, you maintain the list by adding on join and removing on leave.

Note: Only connections with announce: true will appear in the list. The total field will be the total number of connections, regardless of whether they are announced or not.

Basic Usage

const channel = connect('my-chat', {
  as: 'Alice',
  announce: true,
  list: true,        // request the current user list on join
})

// listen for the join event
channel.on('join', joinListener)

// FIRST JOIN EVENT PAYLOAD:
{
  type: 'join',
  uid: 'abc123',       // your own uid
  alias: 'Alice',      // your own alias
  self: true,
  users: [{ uid: 'abc123', alias: 'Alice', self: true }, ...],
  total: 5,
  date: 1710000000000, // server timestamp
}

// SUBSEQUENT JOIN EVENT PAYLOAD:
{
  type: 'join',
  uid: 'def456',       // another user's uid
  alias: 'Bob',        // another user's alias
  total: 6,
  date: 1710000000000, // server timestamp
}

Note: The users field is only present on your own first join event. Subsequent join events from other users won't include it — you track those individually.

User Objects

Each entry in the users array contains:

Field	Type	Description
`uid`	`string`	Unique connection ID
`alias`	`string?`	Display name (if set via `as`)
`self`	`boolean?`	True for your own entry

How It Works

You connect with { list: true, announce: true }
The server sends your join event with a users array of all currently announced users
Other clients receive a normal join event (with your uid and alias)
You maintain the list locally using join and leave events

No polling or custom protocols needed — the server handles the snapshot, and join/leave events keep it in sync.

Next: Sending Messages — send typed messages, direct messages, and more.