Merge pull request #8462 from nextcloud/feature/8338/breakout-rooms-api-4

🖖 Breakout rooms 🛠️ API - Part 4

3 files changed, 60 insertions, 27 deletions

diff --git a/docs/breakout-rooms.md b/docs/breakout-rooms.md
index a94f5ba48..4e1790e76 100644
--- a/docs/breakout-rooms.md
+++ b/docs/breakout-rooms.md
@@ -17,22 +17,22 @@ Group and public conversations can be used to host breakout rooms.
 * Endpoint: `/breakout-rooms/{token}`
 * Data:
 
-| field         | type   | Description                                                                                          |
-|---------------|--------|------------------------------------------------------------------------------------------------------|
-| `mode`        | int    | Participant assignment mode (see [constants list](constants.md#breakout-room-modes))                 |
-| `amount`      | int    | Number of breakout rooms to create (Minimum `1`, maximum `20`)                                       |
-| `attendeeMap` | string | A json encoded Map of attendeeId => room number (0 based) (Only considered when the mode is "manual" |
+| field         | type   | Description                                                                                           |
+|---------------|--------|-------------------------------------------------------------------------------------------------------|
+| `mode`        | int    | Participant assignment mode (see [constants list](constants.md#breakout-room-modes))                  |
+| `amount`      | int    | Number of breakout rooms to create (Minimum `1`, maximum `20`)                                        |
+| `attendeeMap` | string | A json encoded Map of attendeeId => room number (0 based) (Only considered when the mode is "manual") |
 
 * Response:
     - Status code:
         + `200 OK`
-        + `400 Bad Request` When breakout rooms are disabled on the server
-        + `400 Bad Request` When breakout rooms are already configured
-        + `400 Bad Request` When the conversation is not a group conversation
-        + `400 Bad Request` When the conversation is a breakout room itself
-        + `400 Bad Request` When the mode is invalid
-        + `400 Bad Request` When the amount is below the minimum or above the maximum
-        + `400 Bad Request` When the attendee map contains an invalid room number
+        + `400 Bad Request` Error `config`: When breakout rooms are disabled on the server
+        + `400 Bad Request` Error `mode`: When breakout rooms are already configured
+        + `400 Bad Request` Error `room`: When the conversation is not a group conversation
+        + `400 Bad Request` Error `room`: When the conversation is a breakout room itself
+        + `400 Bad Request` Error `mode`: When the mode is invalid
+        + `400 Bad Request` Error `amount`: When the amount is below the minimum or above the maximum
+        + `400 Bad Request` Error `attendeeMap`: When the attendee map contains an invalid room number or moderator
         + `403 Forbidden` When the current user is not a moderator/owner
         + `404 Not Found` When the conversation could not be found for the participant
 
@@ -57,7 +57,7 @@ Group and public conversations can be used to host breakout rooms.
 * Response:
 	- Status code:
 		+ `200 OK`
-		+ `400 Bad Request` When breakout rooms are not configured
+		+ `400 Bad Request` Error `mode`: When breakout rooms are not configured
 		+ `403 Forbidden` When the current user is not a moderator/owner
 		+ `404 Not Found` When the conversation could not be found for the participant
 
@@ -70,7 +70,7 @@ Group and public conversations can be used to host breakout rooms.
 * Response:
 	- Status code:
 		+ `200 OK`
-		+ `400 Bad Request` When breakout rooms are not configured
+		+ `400 Bad Request` Error `mode`: When breakout rooms are not configured
 		+ `403 Forbidden` When the current user is not a moderator/owner
 		+ `404 Not Found` When the conversation could not be found for the participant
 
@@ -89,11 +89,31 @@ Group and public conversations can be used to host breakout rooms.
 * Response:
 	- Status code:
 		+ `201 Created`
-		+ `400 Bad Request` When the room does not have breakout rooms configured
+		+ `400 Bad Request` Error `mode`: When the room does not have breakout rooms configured
 		+ `403 Forbidden` When the participant is not a moderator
 		+ `404 Not Found` When the conversation could not be found for the participant
 		+ `413 Payload Too Large` When the message was longer than the allowed limit of 32000 characters (check the `spreed => config => chat => max-length` capability for the limit)
 
+## Reorganize attendees
+
+* Required capability: `breakout-rooms-v1`
+* Method: `POST`
+* Endpoint: `/breakout-rooms/{token}/attendees`
+* Data:
+
+| field         | type   | Description                                                                                           |
+|---------------|--------|-------------------------------------------------------------------------------------------------------|
+| `attendeeMap` | string | A json encoded Map of attendeeId => room number (0 based) (Only considered when the mode is "manual") |
+
+* Response:
+	- Status code:
+		+ `200 OK`
+		+ `400 Bad Request` Error `config`: When breakout rooms are disabled on the server
+		+ `400 Bad Request` Error `mode`: When breakout rooms are not configured
+		+ `400 Bad Request` Error `attendeeMap`: When the attendee map contains an invalid room number or moderator
+		+ `403 Forbidden` When the current user is not a moderator/owner
+		+ `404 Not Found` When the conversation could not be found for the participant
+
 ## Request assistance
 
 This endpoint allows participants to raise their hand (token is the breakout room) and moderators will see it in any of the breakout rooms as well as the parent room.
@@ -104,7 +124,7 @@ This endpoint allows participants to raise their hand (token is the breakout roo
 * Response:
 	- Status code:
 		+ `200 OK`
-		+ `400 Bad Request` When the room is not a breakout room or breakout rooms are not started
+		+ `400 Bad Request` Error `room`: When the room is not a breakout room or breakout rooms are not started
 		+ `404 Not Found` When the conversation could not be found for the participant
 
 ## Reset request for assistance
@@ -115,7 +135,7 @@ This endpoint allows participants to raise their hand (token is the breakout roo
 * Response:
 	- Status code:
 		+ `200 OK`
-		+ `400 Bad Request` When the room does not have breakout rooms configured
+		+ `400 Bad Request` Error `room`: When the room does not have breakout rooms configured
 		+ `404 Not Found` When the conversation could not be found for the participant
 
 ## List all breakout rooms
@@ -139,7 +159,8 @@ This endpoint allows participants to raise their hand (token is the breakout roo
 * Response:
 	- Status code:
 		+ `200 OK`
-		+ `400 Bad Request` When the participant is a moderator in the conversation
-		+ `400 Bad Request` When breakout rooms are not configured in `free` mode
-		+ `400 Bad Request` When breakout rooms are not started
+		+ `400 Bad Request` Error `moderator`: When the participant is a moderator in the conversation
+		+ `400 Bad Request` Error `mode`: When breakout rooms are not configured in `free` mode
+		+ `400 Bad Request` Error `status`: When breakout rooms are not started
+		+ `400 Bad Request` Error `target`: When the target room is not breakout room of the parent
 		+ `404 Not Found` When the conversation could not be found for the participant
diff --git a/docs/conversation.md b/docs/conversation.md
index bab915cc6..c5362c564 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -96,16 +96,20 @@
 
 ## Creating a new conversation
 
+*Note:* Creating a conversation as a child breakout room, will automatically set the lobby when breakout rooms are not started and will always overwrite the room type with the parent room type. Also moderators of the parent conversation will be automatically added as moderators.
+
 * Method: `POST`
 * Endpoint: `/room`
 * Data:
 
-| field      | type   | Description                                                                                                                                                          |
-|------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `roomType` | int    | See [constants list](constants.md#conversation-types)                                                                                                                |
-| `invite`   | string | user id (`roomType = 1`), group id (`roomType = 2` - optional), circle id (`roomType = 2`, `source = 'circles'`], only available with `circles-support` capability)) |
-| `source`   | string | The source for the invite, only supported on `roomType = 2` for `groups` and `circles` (only available with `circles-support` capability)                            |
-| `roomName` | string | Conversation name up to 255 characters (Not available for `roomType = 1`)                                                                                            |
+| field        | type   | Description                                                                                                                                                           |
+|--------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `roomType`   | int    | See [constants list](constants.md#conversation-types)                                                                                                                 |
+| `invite`     | string | user id (`roomType = 1`), group id (`roomType = 2` - optional), circle id (`roomType = 2`, `source = 'circles'`], only available with `circles-support` capability))  |
+| `source`     | string | The source for the invite, only supported on `roomType = 2` for `groups` and `circles` (only available with `circles-support` capability)                             |
+| `roomName`   | string | Conversation name up to 255 characters (Not available for `roomType = 1`)                                                                                             |
+| `objectType` | string | Type of an object this room references, currently only allowed value is `room` to indicate the parent of a breakout room                                              |
+| `objectId`   | string | Id of an object this room references, room token is used for the parent of a breakout room                                                                            |
 
 * Response:
     - Status code:
@@ -157,7 +161,7 @@
 
 ## Get breakout rooms
 
-Get all (for moderators and in case of "free selection) or the assigned breakout room
+Get all (for moderators and in case of "free selection") or the assigned breakout room
 
 * Required capability: `breakout-rooms-v1`
 * Method: `GET`
@@ -193,6 +197,8 @@ Get all (for moderators and in case of "free selection) or the assigned breakout
 
 ## Delete a conversation
 
+*Note:* Deleting a conversation that is the parent of breakout rooms, will also delete them.
+
 * Method: `DELETE`
 * Endpoint: `/room/{token}`
 
diff --git a/docs/participant.md b/docs/participant.md
index 69bfb0c7c..0a1ffdd08 100644
--- a/docs/participant.md
+++ b/docs/participant.md
@@ -44,6 +44,12 @@
 
 ## Add a participant to a conversation
 
+*Note:* Adding a participant to a breakout room will automatically add them to the parent room as well.
+
+*Note:* Only source users can be added directly to a breakout room.
+
+*Note:* Adding a participant to a breakout room, that is already a participant in another breakout room of the same parent will remove them from there.
+
 * Method: `POST`
 * Endpoint: `/room/{token}/participants`
 * Data: