> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.band.ai/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 the agent is in.

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 track who else is in the conversation. When a participant joins, leaves, or the room itself is deleted, this channel notifies the agent so it can keep its internal participant map in sync and route delegations accurately.

## Where It Fits

1. **Connect** to the WebSocket with agent credentials
2. **Join `room_participants:{roomId}`** for each room the agent is in
3. **Receive `participant_added`** when someone new joins
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 agent 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 /agent/chats/{id}/participants` when you need the latest state.

For the high-level view of which rooms the agent is in, see [Agent Rooms](/websocket/agent/agent-rooms/agent-rooms-channel).

## Events

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