blob: c77a9d9bef3b9cc716a3e9d3c11f0e8cd14e33fe (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
# 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](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` 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](conversation.md#get-user-s-conversations) (API v4)
## 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](conversation.md#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](conversation.md#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](conversation.md#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](conversation.md#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](conversation.md#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](conversation.md#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](conversation.md#get-user-s-conversations) (API v4)
## List all breakout rooms
See [conversation API](conversation.md#get-breakout-rooms))
## Switch to a different breakout room (as non moderator)
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}/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](conversation.md#get-user-s-conversations) (API v4)
|
