Breakout Rooms

Breakout rooms let you split participants from a main video session (the parent room) into smaller sub-groups for focused discussion, then bring everyone back together. Think of it as a meeting's equivalent of sending teams to separate conference rooms mid-session.

Lifecycle & Key Concepts

The flow of a breakout session is:

1. A creator (typically the moderator) calls createBreakoutRoom() to provision one or more breakout rooms.
2. The creator calls inviteToBreakoutRoom() to invite specific participants into each room. Or use createAndInviteBreakoutRoom() to auto-assign participants.
3. Invited participants receive the join-breakout-room event and can accept (via joinBreakOutRoom()) or reject (via rejectBreakOutRoomInvite()).
4. In the breakout room, participants can optionally pause or mute the parent room while working.
5. When done, participants call disconnect() on the breakout room to return to the parent room.
6. The moderator can clear or destroy all breakout rooms at once.

Create a Breakout Room

EnxRoom.createBreakoutRoom() provisions one or more breakout rooms with the specified configuration. The callback returns the room IDs for the created rooms — save these to use when inviting participants.

• Method: EnxRoom.createBreakoutRoom(RoomDefinition, Callback)

var roomDefinition = {
  participants: 3,
  audio:        true,
  video:        false,   // Not yet supported
  canvas:       false,
  share:        true,
  max_rooms:    2        // Create 2 breakout rooms at once
};

room.createBreakoutRoom(roomDefinition, function(data) {
  if (data.result === 0) {
    var breakoutRoomIds = data.msg.rooms;
    console.log("Breakout rooms created:", breakoutRoomIds);
    // Now invite participants using these room IDs
  }
});

Create & Auto-Assign Participants

EnxRoom.createAndInviteBreakoutRoom() creates breakout rooms and randomly distributes participants into them based on each room's capacity. Useful for workshops where group composition does not matter.

• Method: EnxRoom.createAndInviteBreakoutRoom(RoomDefinition, Callback)

var roomDefinition = {
  participants: 4,
  audio:        true,
  video:        false,
  canvas:       false,
  share:        false,
  max_rooms:    3    // Create 3 groups; participants are randomly assigned
};

room.createAndInviteBreakoutRoom(roomDefinition, function(data) {
  if (data.result === 0) {
    console.log("Participants assigned to breakout rooms:", data.msg.rooms);
  }
});

Invite Participants to a Breakout Room

EnxRoom.inviteToBreakoutRoom() sends invitations to specific participants to join a breakout room. By default, participants receive the invitation and choose whether to join. Set force_join: true to move them automatically (SDK v2.0.1+).

• Method: EnxRoom.inviteToBreakoutRoom(invitee, Callback)
• Events (on invited participant):
  • join-breakout-room — when force_join is false or omitted (user chooses)
  • breakout-room-joining — when force_join: true (auto-joining in progress)
  • breakout-room-connected — confirmed connection to the breakout room

var invitee = {
  clients:    ["alice-client-id", "bob-client-id"],
  room_id:    breakoutRoomId,
  force_join: false   // true = auto-join without user's choice
};

room.inviteToBreakoutRoom(invitee, function(resp) {
  if (resp.result === 0) {
    console.log("Invitations sent");
  }
});

// ─── On the INVITED participant's side ─────────────────────────────────

// When force_join is false — participant can choose
room.addEventListener("join-breakout-room", function(event) {
  var breakoutRoomId = event.message.room_id;
  var requestorId    = event.message.requestor;

  // Show accept/decline UI to user
  showBreakoutInviteDialog(breakoutRoomId, requestorId);
});

// When force_join is true — auto-joining in progress
room.addEventListener("breakout-room-joining", function(event) {
  showJoiningSpinner();
});

// Confirmed connection
room.addEventListener("breakout-room-connected", function(roomMeta) {
  // roomMeta contains breakout room metadata
  switchToBreakoutRoomUI();
});

Join a Breakout Room

Called by the invited participant to accept the invitation and join. Must be called from the parent room context.

• Method: EnxRoom.joinBreakOutRoom(Joinee, StreamInfo, Callback)

var joinee = {
  role:    "participant",  // or "moderator"
  room_id: breakoutRoomId
};

var streamInfo = {
  audio:  true,
  video:  false,   // Not supported in breakout rooms
  screen: false,
  canvas: false
};

room.joinBreakOutRoom(joinee, streamInfo, function(resp) {
  console.log("Join request sent");
});

// Connected successfully
room.addEventListener("breakout-room-connected", function(roomMeta) {
  switchToBreakoutRoomUI(roomMeta);
});

// Failed to connect
room.addEventListener("breakout-room-error", function(result) {
  // result.result — error code
  // result.msg    — reason e.g. "Failed to generate Token"
  showError(result.msg);
});

// Others in the breakout room are notified
room.addEventListener("user-joined-breakout-room", function(result) {
  // result.clientId — who joined
  // result.room     — which breakout room
  addParticipantToBreakoutUI(result.clientId);
});

Reject a Breakout Room Invitation

Invited participants can decline the invitation. The moderator is notified.

• Method: EnxRoom.rejectBreakOutRoomInvite(roomId, Callback)
• Event (on moderator): breakout-invite-rejected

// Participant rejects the invitation
room.rejectBreakOutRoomInvite(breakoutRoomId, function(resp) {
  console.log("Invitation rejected");
});

// Moderator is notified
room.addEventListener("breakout-invite-rejected", function(result) {
  // Show which participant rejected
  updateBreakoutAssignmentUI();
});

Pause the Parent Room

After joining a breakout room, participants can pause their parent room connection to save resources and avoid audio/video from both rooms simultaneously.

• Method: EnxRoom.pauseRoom(Callback)

// Called on the parent room object after joining breakout
parentRoom.pauseRoom(function(resp) {
  // resp: { result: 0, msg: "Room paused" }
  console.log("Parent room paused");
});

Resume the Parent Room

Resume the parent room connection after returning from the breakout.

• Method: EnxRoom.resumeRoom(Callback)

parentRoom.resumeRoom(function(resp) {
  // resp: { result: 0, msg: "Room resumed" }
  console.log("Parent room resumed");
});

Mute / Unmute the Parent Room

While in a breakout room, mute the parent room's audio and/or video so it does not interfere with the breakout session.

• Mute: EnxRoom.muteRoom(muteInfo, Callback)
• Unmute: EnxRoom.unMuteRoom(unmuteInfo, Callback)

// Mute parent room audio and video while in breakout
parentRoom.muteRoom({ audio: true, video: true }, function(resp) {
  // resp: { result: 0, msg: "Room muted" }
});

// Unmute after returning to parent room
parentRoom.unMuteRoom({ audio: true, video: true }, function(resp) {
  // resp: { result: 0, msg: "Room unmuted" }
});

Disconnect from a Breakout Room

Call disconnect() on the breakout room object (not the parent room) to leave the breakout room and return to the parent room.

• Method: EnxRoom.disconnect() — called on the breakout room object
• Events:
  • breakout-room-disconnected — acknowledgment to the departing participant
  • user-disconnected-breakout-room — notification to remaining breakout participants

// breakoutRoom is the room object received in breakout-room-connected
breakoutRoom.disconnect();

// Your confirmation that you left
room.addEventListener("breakout-room-disconnected", function(event) {
  switchToParentRoomUI();
  parentRoom.resumeRoom(function() {});
});

// Others in breakout room are notified
room.addEventListener("user-disconnected-breakout-room", function(event) {
  removeParticipantFromBreakoutUI();
});

Clear All Breakout Rooms (SDK v2.0.1+)

clearAllBreakOutSession() disconnects all participants from all breakout rooms and returns them to the parent room simultaneously. The parent room is automatically resumed for everyone.

• Method: EnxRoom.clearAllBreakOutSession()
• Event: breakout-user-disconnected — received by the moderator for each disconnected participant

room.clearAllBreakOutSession();

room.addEventListener("breakout-user-disconnected", function(event) {
  // event.message.room_id   — which breakout room
  // event.message.client_id — who was disconnected
  updateBreakoutStatusUI();
});

Destroy All Breakout Rooms (SDK v2.0.1+)

destroyAllBreakOutSession() terminates all breakout rooms permanently. All participants are moved back to the parent room, which is automatically resumed and unmuted.

• Method: EnxRoom.destroyAllBreakOutSession()
• Event: breakout-room-destroyed

room.destroyAllBreakOutSession();

room.addEventListener("breakout-room-destroyed", function(event) {
  // Breakout rooms are gone — all users back in parent room
  switchToParentRoomUI();
});