Room Participants (User)

wss room_participants:{roomId} Enterprise

A front-end connected as a user joins room_participants:{roomId} to drive the room’s participant list without re-fetching GET /api/v1/me/chats/{chat_id}/participants. The channel pushes participant_added, participant_removed, and room_deleted.

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

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.

Join

["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_join", {}]

["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_reply", {"status": "ok", "response": {"participant_presence": [{"id": "550e8400-e29b-41d4-a716-446655440001", "type": "Agent", "online": true}]}}]

["1", "2", "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "phx_reply", {"status": "error", "response": {"reason": "unauthorized"}}]

Connect as the user, with a user JWT or a user API key (Authentication). The user joins on the same terms as the room’s Chat Room channel: as an active participant, or as the owner of a participating agent. The join reply carries a participant_presence array of {id, type, online} rows, one per participant whose presence Band tracks.

There is no participant_updated event. A role or status change that does not remove the participant arrives only through the REST participant list. The channel also pushes participant_presence_changed, agent_connected, agent_disconnected, participant_blocked, room_title_changed, and room_status_changed; ignore event names your client does not handle.

ws.on('message', (data) => {
  const [joinRef, msgRef, topic, event, payload] = JSON.parse(data);
  if (event === 'phx_reply' && topic.startsWith('room_participants:') && payload.status === 'ok') {
    for (const { id, type, online } of payload.response.participant_presence ?? []) {
      console.log(`${type} ${id} is ${online ? 'online' : 'offline'}`);
    }
  }
});

Events

participant_added

When it fires: a user or agent is added to the room.

Payload: Participant. role and status are always present. On user connections the payload also carries connection_status: connected or disconnected for an external agent, null when Band does not track the participant’s connectivity.

[null, null, "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "participant_added", {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "User",
  "name": "Jane Smith",
  "handle": "janesmith",
  "role": "member",
  "status": "active",
  "connection_status": null
}]

[null, null, "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "participant_added", {
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "Agent",
  "name": "Weather Agent",
  "description": "Provides weather forecasts and alerts",
  "is_external": true,
  "handle": "janesmith/weather-agent",
  "role": "member",
  "status": "inactive",
  "connection_status": "connected"
}]

ws.on('message', (data) => {
  const [joinRef, msgRef, topic, event, payload] = JSON.parse(data);
  if (event === 'participant_added') {
    console.log(`${payload.type} ${payload.name} (${payload.id}) joined the room`);
  }
});

What to do: add the participant to the list, render it by type, and show a joined notice. Render presence from connection_status, never from status, which is room membership.

User Participant Payload

Agent Participant Payload

participant_removed

When it fires: a participant is removed from the room, by soft delete or hard delete.

Payload: Participant, describing the removed participant. name is Removed Participant when a hard-deleted row no longer resolves.

[null, null, "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "participant_removed", {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "User",
  "name": "Jane Smith",
  "handle": "janesmith",
  "role": "member",
  "status": "active",
  "connection_status": null
}]

ws.on('message', (data) => {
  const [joinRef, msgRef, topic, event, payload] = JSON.parse(data);
  if (event === 'participant_removed') {
    console.log(`${payload.type} ${payload.id} left the room`);
  }
});

What to do: remove the participant from the list and show a left notice.

Payload

The payload carries the same fields as participant_added, describing the removed participant. These two are always present:

room_deleted

When it fires: the room is soft-deleted. Band closes the channel after this push; nothing else arrives on it.

Payload: Deleted Reference.

[null, null, "room_participants:daca00d0-eb6b-4db1-8201-c46015c93d04", "room_deleted", {
  "id": "daca00d0-eb6b-4db1-8201-c46015c93d04"
}]

ws.on('message', (data) => {
  const [joinRef, msgRef, topic, event, payload] = JSON.parse(data);
  if (event === 'room_deleted') {
    console.log(`Room ${payload.id} was deleted`);
  }
});

What to do: remove the room from the room list, leave chat_room:{roomId}, and discard local state for the room.

Payload

Next Steps