|
| 1 | +--- |
| 2 | +author: insravan |
| 3 | +ms.service: azure-communication-services |
| 4 | +ms.topic: include |
| 5 | +ms.date: 07/15/2024 |
| 6 | +ms.author: insravan |
| 7 | +--- |
| 8 | +[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)] |
| 9 | + |
| 10 | +`BreakoutRooms` is a `feature` of the class `Call`. First you need to import package `Features` from the Calling SDK: |
| 11 | + |
| 12 | +```js |
| 13 | +import { Features} from "@azure/communication-calling"; |
| 14 | +``` |
| 15 | +### Create breakoutRoom feature |
| 16 | + |
| 17 | +Then you can get the feature API object from the call instance: |
| 18 | +```js |
| 19 | +const breakoutRoomsFeature = mainMeetingCall.feature(Features.BreakoutRooms); |
| 20 | +``` |
| 21 | +### Subscribe to breakoutRoom events |
| 22 | + |
| 23 | +The `BreakoutRooms` API allows you to subscribe to `BreakoutRooms` events. A `breakoutRoomsUpdated` event comes from a `BreakoutRoomsCallFeature` instance and contains information about the created, updated and assigned breakout rooms. |
| 24 | + |
| 25 | +To receive breakout room details, subscribe to the `breakoutRoomsUpdated` event. |
| 26 | +```js |
| 27 | +breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener); |
| 28 | +``` |
| 29 | + |
| 30 | +### Handle breakoutRoom events |
| 31 | + |
| 32 | +Event **breakoutRoomsUpdated** provides instance of one of the following classes as an input parameter. You can use property `type` to distinguish between individual event types. |
| 33 | + |
| 34 | +1. Class `BreakoutRoomsEvent`: This event is triggered when a user with a role organizer, co-organizer, or breakout room manager creates or updates the breakout rooms. Microsoft 365 users with role organizer, co-organizer or breakout room manager can receive this type of event. Developers can use the breakout rooms in property `data` to render details about all breakout rooms. This class has property `type` equal to `"breakoutRooms"`. |
| 35 | + ```js |
| 36 | + export interface BreakoutRoomsEvent { |
| 37 | + /** |
| 38 | + * Breakout room event type |
| 39 | + */ |
| 40 | + type: "breakoutRooms", |
| 41 | + /** |
| 42 | + * list of Breakout rooms |
| 43 | + */ |
| 44 | + data: BreakoutRoom[] | undefined; |
| 45 | + } |
| 46 | + ``` |
| 47 | + |
| 48 | +2. Class `BreakoutRoomsSettingsEvent`: This event is triggered when a user with a role organizer, co-organizer, or breakout room manager updates the breakout room's settings. Developers can use this information to render the time when breakout room ends or decide whether to render button to join main room. This class has property `type` equal to `"breakoutRoomSettings"`. |
| 49 | + ```js |
| 50 | + export interface BreakoutRoomSettingsEvent { |
| 51 | + /** |
| 52 | + * Breakout room event type |
| 53 | + */ |
| 54 | + type: "breakoutRoomSettings", |
| 55 | + /** |
| 56 | + * Breakout Room setting details |
| 57 | + */ |
| 58 | + data: BreakoutRoomSettings | undefined; |
| 59 | + } |
| 60 | + ``` |
| 61 | + |
| 62 | +3. Class `AssignedBreakoutRoomsEvent`: This event is triggered when user is assigned to a breakout room, or assigned breakout room is updated. Users can join the breakout room when property `state` is set to `open`, leave the breakout room when property `state` is set to `closed` or render details of the breakout room. This class has property `type` equal to `"assignedBreakoutRoom"`. |
| 63 | + |
| 64 | + ```js |
| 65 | + export interface AssignedBreakoutRoomEvent { |
| 66 | + /** |
| 67 | + * Breakout room event type |
| 68 | + */ |
| 69 | + type: "assignedBreakoutRoom"; |
| 70 | + /** |
| 71 | + * Assigned breakout room details |
| 72 | + */ |
| 73 | + data: BreakoutRoom | undefined; |
| 74 | + } |
| 75 | + ``` |
| 76 | + |
| 77 | +4. Class `JoinBreakoutRoomsEvent` : This event is triggered when the participant is joining breakout room call. This event can happen when user is automatically moved to breakout room (that is, if `assignedBreakoutRoom` has property `state` set to `open` and `autoMoveParticipantToBreakoutRoom` is set to `true`) or when user explicitly joins breakout room (that is, calls method `join` on the instance `assignedBreakoutRoom` when `autoMoveParticipantToBreakoutRoom` is set to `false`). Property `data` contains the breakout room `call` instance, that developers can use to control breakout room call. This class has property `type` equal to `"join"`. |
| 78 | + ```js |
| 79 | + export interface JoinBreakoutRoomEvent { |
| 80 | + /** |
| 81 | + * Breakout room event type |
| 82 | + */ |
| 83 | + type: "join"; |
| 84 | + /** |
| 85 | + * Breakoutroom call object |
| 86 | + */ |
| 87 | + data: Call | TeamsCall; |
| 88 | + } |
| 89 | + ``` |
| 90 | +The following code shows you valuable information received in the breakout room events: |
| 91 | +```js |
| 92 | + const breakoutRoomsUpdatedListener = (event) => { |
| 93 | + switch(event.type) { |
| 94 | + case "breakoutRooms": |
| 95 | + const breakoutRooms = event.data; |
| 96 | + console.log(`Breakout rooms are created or updated. There are ${breakoutRooms.length} breakout rooms in total.`); |
| 97 | + breakoutRooms.forEach((room)=>{ |
| 98 | + console.log(`- ${room.displayName}`); |
| 99 | + }); |
| 100 | + break; |
| 101 | + case "assignedBreakoutRooms": |
| 102 | + const assignedRoom = event.data; |
| 103 | + console.log(`You are assigned to breakout room named: ${assignedRoom.displayName}`); |
| 104 | + console.log(`Assigned breakout room thread Id: ${assignedRoom.threadId}`); |
| 105 | + console.log(`Automatically move participants to breakout room: ${assignedRoom.autoMoveParticipantToBreakoutRoom}`); |
| 106 | + console.log(`Assigned breakout room state : ${assignedRoom.state }`); |
| 107 | + break; |
| 108 | + case "breakoutRoomsSettings": |
| 109 | + const breakoutRoomSettings = event.data; |
| 110 | + console.log(`Breakout room ends at: ${breakoutRoomSettings.roomEndTime}`); |
| 111 | + console.log(`Disable the user to return to main meeting from breakout room call : ${breakoutRoomSettings.disableReturnToMainMeeting}`); |
| 112 | + break; |
| 113 | + case "join": |
| 114 | + const breakoutRoomCall = event.data; |
| 115 | + console.log(`You have joined breakout room with call ID: ${breakoutRoomCall.id}`); |
| 116 | + break; |
| 117 | + } |
| 118 | + } |
| 119 | +breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener); |
| 120 | +``` |
| 121 | +### List available breakout rooms |
| 122 | + |
| 123 | +Microsoft 365 user with role organizer, co-organizer, or breakout room manager can access all breakout rooms. |
| 124 | +```js |
| 125 | +const breakoutRooms = breakoutRoomsFeature.breakoutRooms; |
| 126 | +breakoutRooms.forEach((room)=>{ |
| 127 | + console.log(`- ${room.displayName}`); |
| 128 | + }); |
| 129 | +``` |
| 130 | + |
| 131 | +### List invitees |
| 132 | + |
| 133 | +Microsoft 365 user with role organizer, co-organizer, or breakout room manager can access participants assigned to individual breakout rooms. |
| 134 | +```js |
| 135 | +breakoutRooms.forEach((room)=>{ |
| 136 | + console.log(`${room.displayName}`); |
| 137 | + room.invitees.forEach((invitee) => { |
| 138 | + console.log(`- ${invitee.id}`); |
| 139 | + }) |
| 140 | + }) |
| 141 | +``` |
| 142 | + |
| 143 | +### Join breakout room |
| 144 | + |
| 145 | +If the `assignedBreakoutRoom` has property `autoMoveParticipantToBreakoutRoom` set to `true`, then the user is automatically moved to the breakout room when the property `state` is set to `open`. If `autoMoveParticipantToBreakoutRoom` is set to `false`, then use the following code to join breakout room. |
| 146 | +This triggers `breakoutRoomsUpdated` event with class `JoinBreakoutRoomsEvent` that has property `type` set as `join`. You can use the instance of a class `call` in property `data` to manage breakout room call. |
| 147 | + |
| 148 | +```js |
| 149 | +const breakoutRoom = breakoutRoomsFeature.assignedBreakoutRoom; |
| 150 | +if(breakoutRoom.state == 'open' && !breakoutRoom.autoMoveParticipantToBreakoutRoom) { |
| 151 | + const breakoutRoomCall = await breakoutRoom.join(); |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +### Leave breakout room |
| 156 | + |
| 157 | +When the breakout room state is `closed`, then the user is automatically moved to the main meeting. User is informed about the end of breakout room by receiving event `breakoutRoomsUpdated` with class `AssignedBreakoutRoomsEvent` and property `type` equal to `assignedBreakoutRooms` that indicates that `assignedBreakoutRoom` has property `state` set to `closed`. |
| 158 | + |
| 159 | +If the user wants to leave the breakout room even before the room is closed and the breakout room settings `breakoutRoomsFeature.breakoutRoomsSettings` have property `disableReturnToMainMeeting` set to `false` then user can join the main meeting call with the following code: |
| 160 | + |
| 161 | +```js |
| 162 | +const breakoutRoomsSettings = breakoutRoomsFeature.breakoutRoomsSettings; |
| 163 | + if(breakoutRoomCall != null && !breakoutRoomsSettings.disableReturnToMainMeeting){ |
| 164 | + breakoutRoomCall.hangUp(); |
| 165 | + mainMeetingCall.resume(); |
| 166 | + } |
| 167 | +``` |
| 168 | + |
| 169 | +### Get participants of the breakout room |
| 170 | + |
| 171 | +When you join the breakout room, you can use the following code to get the list of remote participants of the breakout room: |
| 172 | + |
| 173 | +```js |
| 174 | +const breakoutRoomParticipants = [breakoutRoomCall.remoteParticipants.values()].map((p: SDK.RemoteParticipant) => { p.displayName || p.identifier }); |
| 175 | +console.log(`Participants of the breakoutRoom : <br/>" + breakoutRoomParticipants.join("<br/>")`); |
| 176 | +``` |
| 177 | + |
| 178 | +### Stop receiving breakout rooms events |
| 179 | + |
| 180 | +Use the following code to stop receiving breakoutRooms events |
| 181 | +```js |
| 182 | +breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener); |
| 183 | +``` |
| 184 | +### Breakout room properties |
| 185 | + |
| 186 | +Breakout rooms have the following properties: |
| 187 | + |
| 188 | +```js |
| 189 | +const displayName : string = breakoutRoom.displayName; |
| 190 | +``` |
| 191 | +- `displayName` : Name of the breakout room. This property is read-only. |
| 192 | + |
| 193 | +```js |
| 194 | +const threadId : string = breakoutRoom.threadId; |
| 195 | +``` |
| 196 | +- `threadId` : You can use chat thread ID to join chat of the breakout room. This property is read-only. |
| 197 | + |
| 198 | +```js |
| 199 | +const state : BreakoutRoomState = breakoutRoom.state; |
| 200 | +``` |
| 201 | +- `state` : State of the breakout room. It can be either `open` or `closed`. Users would be able to join the breakout room only when the state is `open`. This property is read-only. |
| 202 | + |
| 203 | +```js |
| 204 | +const autoMoveParticipantToBreakoutRoom : boolean = breakoutRoom.autoMoveParticipantToBreakoutRoom; |
| 205 | +``` |
| 206 | +- `autoMoveParticipantToBreakoutRoom` : Boolean value, which indicates whether the users are moved to breakout rooms automatically when the `state` of `assignedBreakoutRoom` is set to `open`. This property is read-only. |
| 207 | + |
| 208 | +```js |
| 209 | +const call : Call | TeamsCall = breakoutRoom.call; |
| 210 | +``` |
| 211 | +- `call` : Breakout room call object. This is returned when the user joins the breakout room call automatically or by calling `join` method on `assignedBreakoutRoom` object. This property is read-only. |
| 212 | + |
| 213 | +```js |
| 214 | +const invitees : Invitee[] = breakoutRoom.invitees; |
| 215 | +``` |
| 216 | +- `invitees` : The list of invitees who are assigned to the breakout room. This property is read-only. |
| 217 | + |
| 218 | +### Breakout room settings |
| 219 | +Breakout rooms share setting that has the following properties: |
| 220 | +```js |
| 221 | +const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting; |
| 222 | +``` |
| 223 | +- `disableReturnToMainMeeting` : Disable participants to return to the main meeting from the breakout room call. This property is read-only. |
| 224 | + |
| 225 | +```js |
| 226 | +const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime; |
| 227 | +``` |
| 228 | +- `roomEndTime`: Breakout room end time set by the Microsoft 365 user with role organizer, co-organizer, or breakout room manager of the main meeting. This property is read-only. |
| 229 | + |
| 230 | +### Troubleshooting |
| 231 | + |
| 232 | +|Error code| Subcode | Result Category | Reason | Resolution | |
| 233 | +|----------------------------------------------|--------|--------|---------|----------| |
| 234 | +|400 | 46250 | ExpectedError | Breakout Rooms feature is only available in Teams meetings. | Implement your own breakout room mechanism or use Teams meetings. | |
| 235 | +|405 | 46251 | ExpectedError | Azure Communication Services currently disabled this feature. | Try the APIs in a couple of days. | |
| 236 | +|500 | 46254 | UnexpectedServerError | Unable to join breakout room due to an unexpected error. | Ensure that the `state` of `assignedBreakoutRoom` is `open` and call `breakoutRoomsFeature.assignedBreakoutRoom.join()` method explicitly. If the issue persists, gather browser console logs and contact Azure Communication Services support. | |
| 237 | +|500| 46255 | UnexpectedServerError | Unable to hold main meeting. | Ensure that the `state` of `assignedBreakoutRoom` is `open` and call `breakoutRoomsFeature.assignedBreakoutRoom.join()` method explicitly. If the issue persists, gather browser console logs and contact Azure Communication Services support. | |
| 238 | +|412 | 46256| ExpectedError | Unable to join Breakout Room as the room is closed. | Ensure that the `state` of `assignedBreakoutRoom` is `open` and call `breakoutRoomsFeature.assignedBreakoutRoom.join()` method explicitly.| |
| 239 | +|412 | 46257| UnexpectedServerError | Unable to resume main meeting. | Follow the instructions defined in the section `Leave breakout room` for manual leaving of breakout room. If the issue persists, gather browser console logs and contact Azure Communication Services support. | |
| 240 | +|412| 46258 | UnexpectedClientError | Unable to read breakout room details. | Gather browser console logs and contact Azure Communication Services support. | |
| 241 | +|500 | 46259| UnexpectedServerError | Could not hang up the Breakout room call. | Follow the instructions defined in the section `Leave breakout room` for manual leaving of breakout room. | |
| 242 | +|412| 46260 | UnexpectedClientError | Cannot join Breakout Room as it is not yet assigned. | Ensure that the `breakoutRoomsFeature.assignedBreakoutRoom` is having the details of the assigned breakout room. Ensure that the `state` of `assignedBreakoutRoom` is `open` and call `breakoutRoomsFeature.assignedBreakoutRoom.join()` method explicitly. | |
| 243 | + |
| 244 | + |
0 commit comments