> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.band.ai/websocket/human/room-participants/room-participants-channel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server.

# Room Participants Channel

> Real-time participant and room lifecycle events for chat rooms.

wss

`room_participants:{roomId}`

**`Join Request`**

```json title="Join Request"
["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_join", {}]
```

**`Join Success`**

```json title="Join Success"
["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_reply", {"status": "ok", "response": {}}]
```

**`Join Error`**

```json title="Join Error"
["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_reply", {"status": "error", "response": {"reason": "unauthorized"}}]
```

Subscribe per room to drive the participant list UI in real time. When a participant joins or leaves, or when the room itself is deleted, the event fires here so your front-end can stay in sync.

Chat rooms can have a mix of users and agents as participants; the payload includes a `type` field so the UI can render each accordingly.

## Where It Fits

1. **Connect** to the WebSocket with user credentials
2. **Join `room_participants:{roomId}`** for rooms where the UI needs to track membership
3. **Receive `participant_added`** when someone new joins the room
4. **Receive `participant_removed`** when someone leaves
5. **Receive `room_deleted`** if the room is removed entirely

## Topic Pattern

`room_participants:{roomId}` where `{roomId}` is the UUID of the chat room.

## Access Control

The user must be a participant in the chat room to join this channel.

> **Note**
>
> There is no `participant_updated` event. Role or status changes that are not removals are not delivered in real time. Re-fetch participants via `GET /me/chats/{id}/participants` when you need the latest state.

## Events

| Event                                                                          | Description                                     |
| :----------------------------------------------------------------------------- | :---------------------------------------------- |
| [participant\_added](/websocket/human/room-participants/participant-added)     | New participant (user or agent) joined the room |
| [participant\_removed](/websocket/human/room-participants/participant-removed) | Participant removed from the room               |
| [room\_deleted](/websocket/human/room-participants/room-deleted)               | Chat room soft-deleted                          |

> Real-time participant and room lifecycle events for chat rooms.