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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
# Participant API
* API v1: 🏁 Removed with API v4: until Nextcloud 21
* API v2: 🏁 Removed with API v4: Nextcloud 19 - 21
* API v3: 🏁 Removed with API v4: Nextcloud 21 only
* API v4: Base endpoint `/ocs/v2.php/apps/spreed/api/v4`: since Nextcloud 22
## Get list of participants in a conversation
* Method: `GET`
* Endpoint: `/room/{token}/participants`
* Data:
| field | type | Description |
|-----------------|------|-------------------------------------------------------------|
| `includeStatus` | bool | Whether the user status information also needs to be loaded |
* Response:
- Status code:
+ `200 OK`
+ `403 Forbidden` When the participant is a guest
+ `404 Not Found` When the conversation could not be found for the participant
+ `412 Precondition Failed` When the lobby is active and the user is not a moderator
- Data:
Array of participants, each participant has at least:
| field | type | Added | Removed | Description |
|-----------------------|--------|-------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `attendeeId` | int | v3 | | Unique attendee id |
| `actorType` | string | v3 | | Currently known `users |guests|emails|groups|circles`
| `actorId` | string | v3 | | The unique identifier for the given actor type |
| `displayName` | string | v1 | | Can be empty for guests |
| `participantType` | int | v1 | | Permissions level of the participant (see [constants list](constants.md#participant-types)) |
| `lastPing` | int | v1 | | Timestamp of the last ping of the user (should be used for sorting) |
| `inCall` | int | v1 | | Call flags the user joined with (see [constants list](constants.md#participant-in-call-flag)) |
| `permissions` | int | v4 | | Combined final permissions for the participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions)) |
| `attendeePermissions` | int | v4 | | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions)) |
| `sessionId` | string | v1 | v4 | `'0'` if not connected, otherwise a 512 character long string |
| `sessionIds` | array | v4 | | array of session ids, each are 512 character long strings, or empty if no session |
| `status` | string | v2 | | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation |
| `statusIcon` | string | v2 | | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation |
| `statusMessage` | string | v2 | | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation |
| `roomToken` | string | v4 | | Optional: Only available with `breakout-rooms-v1` capability |
## Get list of participants in a conversation including its breakout rooms
* Required capability: `breakout-rooms-v1`
* Method: `GET`
* Endpoint: `/room/{token}/breakout-rooms/participants`
* Data: See Data in `Get list of participants in a conversations`
* Response: See Response in `Get list of participants in a conversations`
## 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:
| field | type | Description |
|------------------|--------|-------------------------------------------------------------------------------------------------------|
| `newParticipant` | string | User, group, email or circle to add |
| `source` | string | Source of the participant(s) as returned by the autocomplete suggestion endpoint (default is `users`) |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the source type is unknown, currently `users`, `groups`, `emails` are supported. `circles` are supported with `circles-support` capability
+ `400 Bad Request` When the conversation is a one-to-one conversation or a conversation to request a password for a share
+ `403 Forbidden` When the current user is not a moderator or owner
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the user or group to add could not be found
- Data:
| field | type | Description |
|--------|------|------------------------------------------------------------------|
| `type` | int | In case the conversation type changed, the new value is returned |
## Delete an attendee by id from a conversation
* Method: `DELETE`
* Endpoint: `/room/{token}/attendees`
* Data:
| field | type | Description |
|--------------|------|---------------------------|
| `attendeeId` | int | The participant to delete |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the participant is a moderator or owner
+ `400 Bad Request` When there are no other moderators or owners left
+ `403 Forbidden` When the current user is not a moderator or owner
+ `403 Forbidden` When the participant to remove is an owner
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the participant to remove could not be found
## Remove yourself from a conversation
* Method: `DELETE`
* Endpoint: `/room/{token}/participants/self`
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the participant is a moderator or owner and there are no other moderators or owners left.
+ `404 Not Found` When the conversation could not be found for the participant
## Join a conversation (available for call and chat)
* Method: `POST`
* Endpoint: `/room/{token}/participants/active`
* Data:
| field | type | Description |
|------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `password` | string | Optional: Password is only required for users which are self joined or guests and only when the conversation has `hasPassword` set to true. |
| `force` | bool | If set to `false` and the user has an active session already a `409 Conflict` will be returned (Default: true - to keep the old behaviour) |
* Response:
- Status code:
+ `200 OK`
+ `403 Forbidden` When the password is required and didn't match
+ `404 Not Found` When the conversation could not be found for the participant
+ `409 Conflict` When the user already has an active Talk session in the conversation with this Nextcloud session. The suggested behaviour is to ask the user whether they want to kill the old session and force join unless the last ping is older than 60 seconds or older than 40 seconds when the conflicting session is not marked as in a call.
- Data in case of `200 OK`: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
- Data in case of `409 Conflict`:
| field | type | Description |
|-------------|--------|--------------------------------------------------------------|
| `sessionId` | string | 512 character long string |
| `inCall` | int | Flags whether the conflicting session is in a potential call |
| `lastPing` | int | Timestamp of the last ping of the conflicting session |
## Resend participant emails
* Required capability: `sip-support`
* Method: `POST`
* Endpoint: `/room/{token}/participants/resend-invitations`
* Data:
| field | type | Description |
|--------------|-------------|------------------------------------------------------------------------------------------|
| `attendeeId` | int or null | Attendee id can be used for guests and users, not setting it will resend all invitations |
* Response:
- Status code:
+ `200 OK`
+ `403 Forbidden` When the current user is not a moderator or owner
+ `404 Not Found` When the given attendee was not found in the conversation
## Leave a conversation (not available for call and chat anymore)
* Method: `DELETE`
* Endpoint: `/room/{token}/participants/active`
* Response:
- Status code:
+ `200 OK`
+ `404 Not Found` When the conversation could not be found for the participant
## Promote a user or guest to moderator
* Method: `POST`
* Endpoint: `/room/{token}/moderators`
* Data:
| field | type | Description |
|--------------|------|----------------------------------------------|
| `attendeeId` | int | Attendee id can be used for guests and users |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the participant to promote is not a normal user (type `3`) or normal guest (type `4`)
+ `403 Forbidden` When the current user is not a moderator or owner
+ `403 Forbidden` When the participant to remove is an owner
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the participant to remove could not be found
## Demote a moderator to user or guest
* Method: `DELETE`
* Endpoint: `/room/{token}/moderators`
* Data:
| field | type | Description |
|--------------|------|----------------------------------------------|
| `attendeeId` | int | Attendee id can be used for guests and users |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the participant to demote is not a moderator (type `2`) or guest moderator (type `6`)
+ `403 Forbidden` When the current participant is not a moderator or owner
+ `403 Forbidden` When the current participant tries to demote themselves
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the participant to demote could not be found
## Set permissions for an attendee
* Method: `PUT`
* Endpoint: `/room/{token}/attendees/permissions`
* Data:
| field | type | Description |
|---------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `attendeeId` | int | Attendee id can be used for guests and users |
| `method` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. |
| `permissions` | int | New permissions for the attendee, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the conversation type does not support setting publishing permissions, e.g. one-to-one conversations
+ `400 Bad Request` When the attendee type is `groups` or `circles`
+ `400 Bad Request` When the mode is invalid
+ `403 Forbidden` When the current user is not a moderator, owner or guest moderator
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the attendee to set publishing permissions could not be found
## Set permissions for all attendees
* Method: `PUT`
* Endpoint: `/room/{token}/attendees/permissions/all`
* Data:
| field | type | Description |
|---------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `method` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. |
| `permissions` | int | New permissions for the attendees, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. |
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the conversation type does not support setting publishing permissions, e.g. one-to-one conversations
+ `400 Bad Request` When the mode is invalid
+ `403 Forbidden` When the current user is not a moderator, owner or guest moderator
+ `404 Not Found` When the conversation could not be found for the participant
## Get a participant by their pin
Note: This is only allowed with validate SIP bridge requests
* Required capability: `sip-support`
* Method: `GET`
* Endpoint: `/room/{token}/pin/{pin}`
* Response:
- Status code:
+ `200 OK`
+ `401 Unauthorized` When the validation as SIP bridge failed
+ `404 Not Found` When the conversation or participant could not be found
- Data: See array definition in `Get user´s conversations`
## Set display name as a guest
* API: Only `v1`
* Method: `POST`
* Endpoint: `/guest/{token}/name`
* Data:
| field | type | Description |
|---------------|--------|----------------------|
| `displayName` | string | The new display name |
* Response:
- Status code:
+ `200 OK`
+ `403 Forbidden` When the current user is not a guest
+ `404 Not Found` When the conversation could not be found for the participant
|
