nextcloud-spreed/docs/breakout-rooms.md

Breakout rooms management

Group and public conversations can be used to host breakout rooms.

• Only moderators can configure and remove breakout rooms
• Only moderators can start and stop breakout rooms
• Moderators in the parent conversation are added as moderators to all breakout rooms and remove from all on demotion

Base endpoint

• API v1: Base endpoint /ocs/v2.php/apps/spreed/api/v1: since Nextcloud 26

Configure breakout rooms

• Required capability: breakout-rooms-v1
• Method: POST
• Endpoint: /breakout-rooms/{token}
• Data:

field	type	Description
mode	int	Participant assignment mode (see constants list)
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 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
  • Data: Array of conversations (breakout rooms and parent) See array definition in Get user´s conversations (API v4)

Create additional breakout room

In order to create an additional breakout room, create a conversation with object type room and object ID being the parent token. See Creating a new conversation for more information.

Delete individual breakout room

The normal deletion API can be used. See Delete a conversation for more information.

Remove breakout rooms

• Required capability: breakout-rooms-v1

• Method: DELETE

• Endpoint: /breakout-rooms/{token}

• Response:

  • Status code:
    • 200 OK
    • 403 Forbidden When the current user is not a moderator/owner
    • 404 Not Found When the conversation could not be found for the participant
  • Data: Parent conversation See array definition in Get user´s conversations (API v4)

Start breakout rooms

• Required capability: breakout-rooms-v1

• Method: POST

• Endpoint: /breakout-rooms/{token}/rooms

• Response:

  • Status code:
    • 200 OK
    • 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
  • Data: Array of conversations (breakout rooms and parent) See array definition in Get user´s conversations (API v4)

Stop breakout rooms

• Required capability: breakout-rooms-v1

• Method: DELETE

• Endpoint: /breakout-rooms/{token}/rooms

• Response:

  • Status code:
    • 200 OK
    • 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
  • Data: Array of conversations (breakout rooms and parent) See array definition in Get user´s conversations (API v4)

Broadcast message to breakout rooms

• Required capability: breakout-rooms-v1
• Method: POST
• Endpoint: /breakout-rooms/{token}/broadcast
• Data:

field	type	Description
message	string	A chat message to be posted in all breakout rooms in the name of the moderator
token	string	Note: The token in the URL is the parent room. The message will appear in all breakout rooms automatically

• Response:
  • Status code:
    • 201 Created
    • 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)
  • Data: Array of conversations (breakout rooms and parent) See array definition in Get user´s conversations (API v4)

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
  • Data: Array of conversations (breakout rooms and parent) See array definition in Get user´s conversations (API v4)

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.

• Required capability: breakout-rooms-v1
• Method: POST
• Endpoint: /breakout-rooms/{token}/request-assistance
• Response:
  • Status code:
    • 200 OK
    • 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
  • Data: Breakout room See array definition in Get user´s conversations (API v4)

Reset request for assistance

• Required capability: breakout-rooms-v1
• Method: DELETE
• Endpoint: /breakout-rooms/{token}/request-assistance
• Response:
  • Status code:
    • 200 OK
    • 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
  • Data: Breakout room See array definition in Get user´s conversations (API v4)

List all breakout rooms

See conversation API)

Switch to a different breakout room (as non moderator)

This endpoint allows participants to switch between breakout rooms when they are allowed to choose the breakout room and not are automatically or manually assigned by the moderator.

• Required capability: breakout-rooms-v1
• Method: POST
• Endpoint: /breakout-rooms/{token}/switch
• Data:

field	type	Description
token	string	(In the URL) Conversation token of the parent room hosting the breakout rooms
target	string	Conversation token of the target breakout room

• Response:
  • Status code:
    • 200 OK
    • 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
  • Data: Target breakout room See array definition in Get user´s conversations (API v4)