Breakout Room

Breakout rooms allow users to participate in a discussion outside the main video room, that is, the parent room.

The process of breaking out takes place in the following manner:

A creator or owner of a breakout room invites one or more users from the parent room to the breakout room.
The invited users are notified about the request and need to accept the request to join the breakout room.
Users moving out of the parent room are treated as "paused" users in the parent room until they return.

Review the following considerations before implementing a breakout room:

A breakout room is available only in the Group Mode room, not in the Lecture mode.
A breakout room can only be created by a user from the parent room. A user cannot create another breakout room while being within a breakout room.
A breakout room can be created with a limit to the maximum number of allowed participants, which must be less than the maximum number of Active Talkers in the parent room.
A breakout room supports only audio calls with screen sharing and canvas streaming features.
A maximum of 10 breakout rooms are allowed for a parent room.

List of Methods

The Web SDK provides the following methods for creating breakout rooms, add and disconnect participants to breakout rooms, and other related tasks:

createBreakOutRoom(): To create a breakout room.
inviteToBreakOutRoom(): To invite one or more users to a breakout room from the parent room.
createAndInviteBreakoutRoom(): To support certain usecases where auto-assignment of users into different breakout rooms is required.
joinBreakOutRoom(): To allow users to join a breakout room on being invited by the creator of the breakout room.
rejectBreakOutRoomInvite(): To reject the invitation to join a breakout room.
pause(): To pause the parent room.
resume(): To resume the parent room.
muteRoom(): To mute audio and/or video of the parent room.
unmuteRoom(): To unmute audio and/or video of the parent room.
disconnect(): To disconnect from a breakout room.
clearAllBreakOutSession(): To allow the participants to clear all breakout rooms.
destroyAllBreakOutSession(): To destroy all the breakout room sessions.

Create a Breakout Room

The EnxRoom.createBreakOutRoom() method creates a breakout room.

Method: EnxRoom.createBreakoutRoom(RoomDefinition, Callback)
Parameters:
- RoomDefinition : Required. JSON Object with Room definition parameters defined as following keys:
  - participants : Number. Required. Total number of Participants in the Break-Out Room. Range: Min: 2. Max: max_active_talkers of Parent Room – 1
  - audio : Boolean. Required. Set to true to enable Audio Communication in Break-Out Room.
  - video : Boolean. Required. Set to true to enable Video Communication in Break-Out Room. (This is currently not supported).
  - canvas : Boolean. Required. Set to true to enable Canvas Streaming in Break-Out Room.
  - share : Boolean. Required. Set to true to enable Screen Share in Break-Out Room.
  - max_rooms : Number. Required. The total number of Break-Out rooms to be created.
- Callback : Callback function. It gets created breakout rooms in a JSON Array.

Sample Code

RoomDefinition = {
	"participants": 2, 
	"audio": true,
	"video": false, 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

room.createBreakoutRoom(RoomDefinition, function(data) {
	// data is JSON with created breakout Room Information 
	/*		
	{	"msg": {
			"rooms": [ "roomIds" ]
		},
		"result": 0
	}
	*/
});

Error Codes

Code	Description
1724	The participant count is not found.
1725	The participant count is more than the size of the parent room.
1726	Permissible limit to create breakout room has exceeded.
1729	Failed to generate the token.
1731	Failed to create a breakout room.
1734	Required parameter missing. Participant count is mandatory.

Invite Users to Join a Breakout Room

The EnxRoom.inviteToBreakOutRoom() method allows the creator or owner of a breakout room to invite one or more users from the parent room to join the breakout room.

This method must be invoked from the parent room and not from the breakout room.

Method: EnxRoom.inviteToBreakoutRoom(invitee, Callback)
Parameters:
- invitee :
  - clients : Array. Client IDs of users to invite.
  - room_id : String. Room ID of the breakout room to which the users are invited.
  - force_join : Boolean. If set to true, the invited participant is forced to join the breakout room. This functionality is available in Web SDK 2.0.1 and later.
- Callback : Callback function. To obtain the result of the invitation process.
Event Listeners:
- join-breakout-room : Notification sent to the invited particicpant when the participant is invited to join a breakout room.
- breakout-room-joining : Notification sent to the invited participant when the participant needs to join the breakout room.
- breakout-room-connected : Notification sent to the invited participant when the participant is connected to the breakout room.

Sample Code

invitee = {
	"clients" : "[clientIds]", 
	"room_id" : "RoomID",
        "force_join" : true
};

room.inviteToBreakoutRoom(invitee, function(resp) {
	// resp is the result of invitation process, for example,
	/*		
	{	"msg": "Success",
		"result": 0,
	}
	*/
});
 
// Notification: Users invited to join, when `force_join: false` is used or omitted,
room.addEventListener("join-breakout-room", function (event) {
	// The event carries the invitation details, for example,
	/*		
	{	"type": 'join-breakout-room', 
		"message": {
			"room_id": "String",
			"requestor": "String"
		}
	}
	*/

	// User may join room now. This is optional.  
	// User may be presented with the UI to either join or reject
	// In case, a user needs to join, read JoinBreakOutRoom() later in the document
	Joinee = {
		"role" : "participant", 
		"room_id" : "RoomID"
	};

	StreamInfo = {
		"audio": true, 
		"video" : false,
		"canvas" : false,
		"screen" : false
	};
	
	room.joinBreakOutRoom(Joinee, StreamInfo, function(resp) {
		// Status 
	});
});

// Notification:  Users invited to join, when `force_join: true` 
room.addEventListener("breakout-room-joining", function (event) {
	// the event carries the invitation details, for example,
	/*		
	{	"type": 'breakout-room-joining', 
		"message": {
			"room_id": "String",
			"requestor": "String"
		}
	}
	*/
});

// Notification:  To invvited users. Break-Out Room joined with `force_join: true`
room.addEventListener("breakout-room-connected", function (event) {
	// the event carries the room meta 
	 
});

Create a Breakout Room and Auto-Invite the Users to the Room

The EnxRoom.createAndInviteBreakoutRoom() is used to support certain use cases where auto-assignment of users into different breakout rooms is required. This method creates a breakout room with defined specifications and randomly invites users to join a breakout room depending on the capacity of the room.

Method: EnxRoom.createAndInviteBreakoutRoom(RoomDefinition, Callback)
Parameters:
- RoomDefinition : JSON Object. Room definition parameters.
- Callback : Callback function. To obtain the result of the Create a Breakout Room method as a JSON array.

More information: Create a Breakout Room.

Sample Code

RoomDefinition = {
	"participants": 2, 
	"audio": true,
	"video": false, 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

room.createAndInviteBreakoutRoom(RoomDefinition, function(data) {
	// data is JSON with created breakout room information, for example, 
	/*		
	{	"msg": {
			"rooms": [ "roomIds" ]
		},
		"result": 0
	}
	*/
});

Join a Breakout Room

The EnxRoom.joinBreakOutRoom() method allows participants to join a breakout room on the breakout room creator's invitation. A participant can join a breakout room from the parent room only and join only one breakout room at a time, thus allowing the participant to join another breakout room only after rejoining the parent room first.

Method: EnxRoom.joinBreakOutRoom(Joinee, streamInfo, Callback)
Parameters:
- Joinee : JSON Object with details required to join the Break-Out Room.
  - role : String. Required. Enumerated Values: participant, moderator.
  - room_id : String. Required. Room-ID of the Break-Out Room being joined.
- streamInfo : JSON Object with Stream information while joining the Break-Out Room.
  - audio : Boolean. Set to true to join with Audio.
  - video : Boolean. Set to true to join with Video. This is currently not supported.
  - screen : Boolean. Set to true for screen sharing capability.
  - canvas : Boolen. Set to true for canvas streaming capability.
- Callback : To know result of the join Room call.
Event Listeners:
- ``breakout-room-error` : Notification to a joiner when the joiner fails to join the breakout room.
- ``breakout-room-connected` : Acknowledgment to a joiner when the joiner successfully joins the breakout room.
- ``user-joined-breakout-room` : Notification to everyone in the breakout room when a new user joins the room.

Sample Code

var Joinee = {
	"role" : "participant", 
	"room_id" : "RoomID"
};

var StreamInfo = {
	"audio": true, 
	"video" : false,
	"canvas" : false,
	"screen" : false
};

room.joinBreakOutRoom(Joinee, StreamInfo, function(resp) {
	// Status 
});

// Notification: Connected to Breakout Room 
room.addEventListener("breakout-room-connected", function (roomMeta) {
	// roomMetadata contains meta information of the Room 
});

// Notification: Failed to connect to Breakout Room 
room.addEventListener("breakout-room-error", function (result) {
	// result contains reasons of failed connection, for example,
	/*
	{	"result": 1729,
		"msg": "Failed to generate Token"
	}
	*/
});

// Notification: To others.   New user joined.
room.addEventListener("user-joined-breakout-room", function (result) {
	// result contains new joinee user's information 
	/*
	{	"clientId": "String",
		"room": "String";
	}
	*/
});

Reject a Breakout Room Invitation

The EnxRoom.rejectBreakOutRoomInvite() allows invited users to reject the invitation to join a breakout room.

Method: EnxRoom.rejectBreakOutRoomInvite(roomId, callback)
Parameters:
- roomId : String. Identifier of the breakout room to which the user is invited.
- Callback : Callback Function. Notification to the moderator when a user rejects an invitation to a breakout room.
Event Listener:
- breakout-invite-rejected: Notification to the moderator when a user rejects an invitation to a breakout room.

Sample Code

// User rejects breakout room invitation.
Room.rejectBreakOutRoomInvitation(roomId, function(resp) {
	// Status 
}); 

// Notification: To moderato. Invited user rejected to join
room.addEventListener("breakout-invite-rejected", function (result) {
	
});

Pause a Parent Room

The EnxRoom.pause() method allows users to pause the parent room after joining the breakout room.

Method: EnxRoom.pauseRoom(Callback)
Parameters:
- Callback: Callback Function. To get status of method call.

Sample Code

room.pauseRoom(function(resp) {
	// resp carries status
	/*
	{	"msg": "Room paused",
		"result": 0
	}
	*/
});

Error Codes

Code	Description
1138	Internal Server Error

Resume a Parent Room

The EnxRoom.resume() method is used to resume the parent room if it was paused while joining the breakout room.

Method: EnxRoom.resumeRoom(Callback)
Parameters:
- Callback: Callback Function. To get status of method call.

Sample Code

room.resumeRoom(function(resp) {
	// resp carries status
	/*
	{	"msg": "Room resumed",
		"result": 0
	}
	*/
});

Error Codes

Code	Description
1138	An internal server error has occurred.

Mute a Parent Room

The EnxRoom.muteRoom() method allows users to mute audio and/or video of the parent room after joining the breakout room.

Method: EnxRoom.muteRoom(muteInfo, Callback)
Parameters:
- muteInfo : JSON Object. Muting options for audio and video.
  - audio : Boolean. Set it to true to mute the audio of the parent room.
  - video : Boolean. Set it to true to mute the video of the parent room.
- Callback : Callback Function. To get status of Method call.

Sample Code

var MuteInfo = {
	"audio" : true, 
	"video" : true
};

room.muteRoom(MuteInfo, function(resp) {
	// resp carries status
	/*
	{	"msg": "Room muted",
		"result": 0
	}
	*/
});

Unmute a Parent Room

The EnxRoom.unmuteRoom() is used to unmute the audio and/or video of the parent room after disconnecting from the breakout room and resuming the parent room.

Method: EnxRoom.unMuteRoom(unmuteInfo, Callback)
Parameters:
- unmuteInfo : JSON Object. Unmuting options for audio and video.
  - audio : Boolean. Set it to true to unmute the audio of the parent room.
  - video : Boolean. Set it to true to unmute the video of the parent room.
- Callback : Callback Function. To get status of Method call.

Sample Code

var UnmuteInfo = {
	"audio" : true, 
	"video" : true
};
room.unMuteRoom(UnmuteInfo, function(resp) {
	// resp carries status
	/*
	{	"msg": "Room unmuted",
		"result": 0
	}
	*/
}

Disconnect from a Breakout Room

The EnxRoom.disconnect() method allows users to disconnect from the breakout room.

Method: EnxRoom.disconnect()
Event Listeners:
- breakout-room-disconnected : Acknowledgment to a particicpant when the particicpant is successfully disconnected from the breakout room.
- user-disconnected-breakout-room : Notification to everyone in the breakout room when a particicpant is disconnected from the room.

Sample Code

breakout_room.disconnect();

// Notification: To disconnected user from breakout room
room.addEventListener("breakout-room-disconnected", function (event) {
	 
});

// Notification: To other users of breakout room
room.addEventListener("user-disconnected-breakout-room", function (event) {
	 
});

Clear All Breakout Rooms

This functionality is available in Web SDK version 2.0.1 and later.

The EnxRoom.clearAllBreakOutSession() method allows participants to clear all breakout rooms. The participants are disconnected from all breakout instances and rejoined with the parent room.

Method: EnxRoom.clearAllBreakOutSession()
Event Listeners:
- breakout-user-disconnected: Notification to the moderator/owner of the breakout room with information about the disconnected participant.

Sample Code

room.addEventListener("breakout-user-disconnected", function (event) {
	/* event JSON: Information of disconnected participant		
	{	"type": 'breakout-user-disconnected', 
		"message: {
			"room_id": "String",
			"client_id": "String"
		}
	}
	*/
});

Handle Destroyed Breakout Rooms

This functionality is available in Web SDK version 2.0.1 and later.

The EnxRoom.destroyAllBreakOutSession() method allows the moderator to destroy all the breakout room sessions. When all the breakout room sessions are destroyed, the parent room is automatically resumed and unmuted for the particicpants.

Method: EnxRoom.destroyAllBreakOutSession()
Event Listener::
- breakout-room-destroyed: Notification to the owner when the breakout room is destroyed.

Sample Code

room.destroyAllBreakOutSession(); 

room.addEventListener("breakout-room-destroyed", function (event) {
	 
});

Session Management Floor Access Controls