Breakout Rooms

Split participants into smaller groups for focused discussions and collaborative sessions

Overview

BaxCloud supports breakout rooms for splitting participants into smaller groups for focused discussions. This feature is ideal for workshops, training sessions, collaborative work, and any scenario where you need to divide a large group into smaller, more intimate conversations.

💡

Host-Only Feature

Only hosts and co-hosts can create and manage breakout rooms. Regular participants can join assigned rooms and move between rooms when permitted.

Create & Assign

Create multiple rooms and assign specific participants to each room

Join & Leave

Participants can join assigned rooms and return to the main room anytime

Real-time Status

Track room status and participant distribution in real-time

Key Features

Multiple Breakout Rooms
Create and manage multiple breakout rooms simultaneously (host/co-host only)
Participant Assignment
Assign specific participants to rooms or allow them to choose their own
Flexible Movement
Join and leave breakout rooms with seamless transitions
Real-time Status Tracking
Monitor participant distribution and room activity
Return to Main Room
Participants can always return to the main session

Creating Breakout Rooms

Host and co-hosts can create breakout rooms with assigned participants

Only hosts and co-hosts have permission to create breakout rooms. You can specify the room name and assign specific participants by their user IDs.

1import { BaxCloudClient } from '@baxcloud/react-sdk';
2
3// Create a breakout room (host only)
4const createRoom = async () => {
5  try {
6    const room = await client.createBreakoutRoom({
7      roomName: 'Design Team Discussion',
8      participantIds: ['user-123', 'user-456', 'user-789']
9    });
10    
11    console.log('Breakout room created:', room.id);
12    console.log('Assigned participants:', room.participantIds);
13  } catch (error) {
14    console.error('Failed to create room:', error);
15    // Error: Only hosts can create breakout rooms
16  }
17};

⚠️

Host Permission Required

Only users with isHost: true or isCoHost: true can create breakout rooms. Regular participants attempting to create rooms will receive a permission error.

Joining Breakout Rooms

Participants can join their assigned breakout rooms

When a participant is assigned to a breakout room, they can join it using the room ID. Joining a breakout room will transition them from the main room to the smaller group session.

1// Join a breakout room
2const joinRoom = async (roomId: string) => {
3  try {
4    await client.joinBreakoutRoom(roomId);
5    console.log('Joined breakout room:', roomId);
6  } catch (error) {
7    console.error('Failed to join room:', error);
8  }
9};
10
11// Example: Join when assigned
12client.on('breakoutRoomCreated', (room) => {
13  const isAssigned = room.participantIds.includes(client.currentUser.userId);
14  
15  if (isAssigned) {
16    console.log('You have been assigned to:', room.roomName);
17    // Auto-join or show prompt
18    await joinRoom(room.id);
19  }
20});

Participants can be assigned to specific rooms or choose their own. When a participant joins a breakout room, they maintain their audio/video state and can continue their conversation in the smaller group.

Leaving Breakout Rooms

Return to the main room from a breakout session

Participants can leave their breakout room at any time to return to the main session. This provides flexibility for participants to move between breakout discussions and the main room.

1// Leave breakout room and return to main room
2const leaveBreakoutRoom = async () => {
3  try {
4    await client.leaveBreakoutRoom();
5    console.log('Returned to main room');
6  } catch (error) {
7    console.error('Failed to leave breakout room:', error);
8  }
9};
10
11// Example UI component
12function BreakoutRoomControls() {
13  const [inBreakoutRoom, setInBreakoutRoom] = useState(false);
14  
15  useEffect(() => {
16    client.on('breakoutRoomJoined', () => setInBreakoutRoom(true));
17    client.on('breakoutRoomLeft', () => setInBreakoutRoom(false));
18  }, []);
19  
20  if (!inBreakoutRoom) return null;
21  
22  return (
23    <button onClick={leaveBreakoutRoom} className="btn-primary">
24      Return to Main Room
25    </button>
26  );
27}

When a participant leaves a breakout room, they are automatically reconnected to the main room session. Their audio and video state is preserved during the transition.

Managing Breakout Rooms

Retrieve and monitor breakout room status

Hosts and participants can retrieve information about all breakout rooms or specific rooms to monitor participant distribution and room activity.

1// Get all breakout rooms
2const rooms = await client.getBreakoutRooms();
3
4rooms.forEach(room => {
5  console.log('Room:', room.roomName);
6  console.log('Participants:', room.participantIds.length);
7  console.log('Status:', room.status); // 'active' | 'closed'
8});
9
10// Get specific breakout room
11const room = await client.getBreakoutRoom(roomId);
12
13console.log('Room name:', room.roomName);
14console.log('Assigned participants:', room.participantIds);
15console.log('Current participants:', room.currentParticipants);
16
17// Check if user is in a breakout room
18const currentRoom = await client.getCurrentBreakoutRoom();
19
20if (currentRoom) {
21  console.log('Currently in:', currentRoom.roomName);
22} else {
23  console.log('In main room');
24}

Use getBreakoutRooms() to display a list of all active breakout rooms and their participant counts. This is useful for hosts to monitor room distribution and activity.

Complete UI Examples

Full breakout room management interfaces

1import { useState, useEffect } from 'react';
2import { BaxCloudClient, useBaxCloudParticipants } from '@baxcloud/react-sdk';
3
4interface BreakoutRoom {
5  id: string;
6  roomName: string;
7  participantIds: string[];
8  currentParticipants: number;
9  status: 'active' | 'closed';
10}
11
12function BreakoutRoomManager({ client }: { client: BaxCloudClient }) {
13  const [rooms, setRooms] = useState<BreakoutRoom[]>([]);
14  const [currentRoom, setCurrentRoom] = useState<BreakoutRoom | null>(null);
15  const [newRoomName, setNewRoomName] = useState('');
16  const [selectedParticipants, setSelectedParticipants] = useState<string[]>([]);
17  const participants = useBaxCloudParticipants();
18  const isHost = client.currentUser?.isHost;
19  
20  useEffect(() => {
21    loadRooms();
22    
23    client.on('breakoutRoomCreated', loadRooms);
24    client.on('breakoutRoomJoined', (room) => setCurrentRoom(room));
25    client.on('breakoutRoomLeft', () => setCurrentRoom(null));
26    
27    return () => {
28      client.off('breakoutRoomCreated', loadRooms);
29    };
30  }, []);
31  
32  const loadRooms = async () => {
33    const allRooms = await client.getBreakoutRooms();
34    setRooms(allRooms);
35    
36    const current = await client.getCurrentBreakoutRoom();
37    setCurrentRoom(current);
38  };
39  
40  const createRoom = async () => {
41    if (!newRoomName || selectedParticipants.length === 0) return;
42    
43    try {
44      await client.createBreakoutRoom({
45        roomName: newRoomName,
46        participantIds: selectedParticipants
47      });
48      
49      setNewRoomName('');
50      setSelectedParticipants([]);
51    } catch (error) {
52      console.error('Failed to create room:', error);
53    }
54  };
55  
56  const toggleParticipant = (userId: string) => {
57    setSelectedParticipants(prev =>
58      prev.includes(userId)
59        ? prev.filter(id => id !== userId)
60        : [...prev, userId]
61    );
62  };
63  
64  return (
65    <div className="breakout-room-manager">
66      {/* Current Room Status */}
67      {currentRoom && (
68        <div className="current-room-banner">
69          <span>Currently in: {currentRoom.roomName}</span>
70          <button onClick={() => client.leaveBreakoutRoom()}>
71            Return to Main Room
72          </button>
73        </div>
74      )}
75      
76      {/* Room List */}
77      <div className="rooms-section">
78        <h3>Breakout Rooms</h3>
79        <div className="rooms-grid">
80          {rooms.map(room => (
81            <div key={room.id} className="room-card">
82              <h4>{room.roomName}</h4>
83              <p>{room.currentParticipants} / {room.participantIds.length} participants</p>
84              <button 
85                onClick={() => client.joinBreakoutRoom(room.id)}
86                disabled={currentRoom?.id === room.id}
87              >
88                {currentRoom?.id === room.id ? 'Current Room' : 'Join'}
89              </button>
90            </div>
91          ))}
92        </div>
93      </div>
94      
95      {/* Create Room (Host Only) */}
96      {isHost && (
97        <div className="create-room-section">
98          <h3>Create Breakout Room</h3>
99          <input
100            type="text"
101            placeholder="Room name"
102            value={newRoomName}
103            onChange={(e) => setNewRoomName(e.target.value)}
104          />
105          
106          <div className="participant-selection">
107            <h4>Select Participants</h4>
108            {participants.map(participant => (
109              <label key={participant.userId} className="participant-checkbox">
110                <input
111                  type="checkbox"
112                  checked={selectedParticipants.includes(participant.userId)}
113                  onChange={() => toggleParticipant(participant.userId)}
114                />
115                <span>{participant.name}</span>
116              </label>
117            ))}
118          </div>
119          
120          <button 
121            onClick={createRoom}
122            disabled={!newRoomName || selectedParticipants.length === 0}
123          >
124            Create Room
125          </button>
126        </div>
127      )}
128    </div>
129  );
130}

Breakout rooms are independent sessions with their own chat and participants. Hosts can broadcast messages to all breakout rooms simultaneously using the broadcast API.

Advanced Features

Time limits, auto-assignments, and broadcasting

Auto-Assignment of Participants

Automatically distribute participants evenly across breakout rooms.

1// Auto-assign participants to rooms
2const autoAssignParticipants = async (roomCount: number) => {
3  const participants = await client.getParticipants();
4  const participantsPerRoom = Math.ceil(participants.length / roomCount);
5  
6  for (let i = 0; i < roomCount; i++) {
7    const start = i * participantsPerRoom;
8    const end = start + participantsPerRoom;
9    const roomParticipants = participants.slice(start, end);
10    
11    await client.createBreakoutRoom({
12      roomName: `Room ${i + 1}`,
13      participantIds: roomParticipants.map(p => p.userId)
14    });
15  }
16};
17
18// Usage
19await autoAssignParticipants(3); // Create 3 rooms with even distribution

Time Limits for Breakout Rooms

Set automatic time limits and notify participants when time is running out.

1// Create room with time limit (in minutes)
2const createTimedRoom = async (roomName: string, participantIds: string[], durationMinutes: number) => {
3  const room = await client.createBreakoutRoom({
4    roomName,
5    participantIds,
6    timeLimit: durationMinutes * 60 * 1000 // Convert to milliseconds
7  });
8  
9  // Set timer to auto-close room
10  setTimeout(async () => {
11    await client.closeBreakoutRoom(room.id);
12    // Notify participants
13    await client.broadcastToBreakoutRooms({
14      message: `${roomName} has ended. Returning to main room.`
15    });
16  }, durationMinutes * 60 * 1000);
17  
18  return room;
19};
20
21// Usage
22await createTimedRoom('Design Discussion', ['user-1', 'user-2'], 15); // 15 minutes

Broadcasting to All Breakout Rooms

Hosts can send messages or announcements to all breakout rooms simultaneously.

1// Broadcast message to all breakout rooms
2const broadcastMessage = async (message: string) => {
3  try {
4    await client.broadcastToBreakoutRooms({ message });
5    console.log('Message broadcast to all rooms');
6  } catch (error) {
7    console.error('Failed to broadcast:', error);
8  }
9};
10
11// Example: Send time warning
12await broadcastMessage('5 minutes remaining in breakout sessions');
13
14// Example: Request return to main room
15await broadcastMessage('Please return to the main room in 2 minutes');

💡

Best Practice

Use broadcasts to send time warnings, important announcements, or instructions to all breakout rooms simultaneously. This ensures all participants receive consistent information regardless of which room they're in.

Event Listeners

Handle breakout room events in real-time

Listen to breakout room events to update your UI and respond to room state changes.

1// Listen for breakout room events
2useEffect(() => {
3  // When a new breakout room is created
4  client.on('breakoutRoomCreated', (room) => {
5    console.log('New room created:', room.roomName);
6    console.log('Assigned participants:', room.participantIds);
7  });
8  
9  // When the current user joins a breakout room
10  client.on('breakoutRoomJoined', (room) => {
11    console.log('Joined room:', room.roomName);
12    setCurrentRoom(room);
13  });
14  
15  // When the current user leaves a breakout room
16  client.on('breakoutRoomLeft', () => {
17    console.log('Left breakout room, returned to main room');
18    setCurrentRoom(null);
19  });
20  
21  // When a breakout room is closed
22  client.on('breakoutRoomClosed', (roomId) => {
23    console.log('Room closed:', roomId);
24  });
25  
26  // When participants join/leave a breakout room
27  client.on('breakoutRoomParticipantsChanged', (room) => {
28    console.log('Participants updated in:', room.roomName);
29    console.log('Current count:', room.currentParticipants);
30  });
31  
32  return () => {
33    client.off('breakoutRoomCreated');
34    client.off('breakoutRoomJoined');
35    client.off('breakoutRoomLeft');
36    client.off('breakoutRoomClosed');
37    client.off('breakoutRoomParticipantsChanged');
38  };
39}, [client]);

All breakout room events are emitted in real-time, allowing you to keep your UI synchronized with the current state of all rooms and participant movements.

Best Practices

1. Clear Communication

Always notify participants when they are assigned to a breakout room and provide clear instructions on how to join and when to return to the main room.

2. Set Time Expectations

Inform participants about the duration of breakout sessions upfront and send reminders when time is running out using the broadcast API.

3. Monitor Room Distribution

Hosts should regularly check participant distribution across rooms and ensure no one is left unassigned or stuck in an empty room.

4. Provide Easy Return Path

Make the "Return to Main Room" button prominent and easily accessible so participants can leave breakout rooms at any time.

5. Handle Edge Cases

Account for scenarios like participants losing connection, rejoining after disconnect, or joining late after rooms have been created.

Next Steps

Chat & Messaging

Learn about chat in breakout rooms and main session

Event Listeners

Handle all real-time events in your application

View Examples

See complete breakout room implementations