* Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
* Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
## Get listed conversations
* Method: `GET`
* Endpoint: `/listed-room`
* Response:
- Status code:
+ `200 OK`
+ `401 Unauthorized` when the user is not logged in
- Header:
field | type | Description
------|------|------------
`searchTerm` | string | search term
- Data: See array definition in `Get user´s conversations`
## Get user´s conversations
* Method: `GET`
@ -65,8 +47,8 @@
`hasCall` | bool | * | Flag if the conversation has an active call
`callFlag` | int | v3 | Combined flag of all participants in the current call (see [constants list](constants.md#participant-in-call-flag), only available with `conversation-call-flags` capability)
`canStartCall` | bool | * | Flag if the user can start a new call in this conversation (joining is always possible) (only available with `start-call-flag` capability)
`canDeleteConversation` | bool | 🆕 v2 | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)
`canLeaveConversation` | bool | 🆕 v2 | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)
`canDeleteConversation` | bool | v2 | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)
`canLeaveConversation` | bool | v2 | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)
`lastActivity` | int | * | Timestamp of the last activity in the conversation, in seconds and UTC time zone
`isFavorite` | bool | * | Flag if the conversation is favorited by the user
`notificationLevel` | int | * | The notification level for the user (one of `Participant::NOTIFY_*` (1-3))
@ -90,7 +72,7 @@
field | type | Description
------|------|------------
`roomType` | int |
`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 (Not available for `roomType = 1`)
@ -124,6 +106,25 @@
- Data: See array definition in `Get user´s conversations`
## Get open conversations
* Required capability: `listable-rooms`
* Method: `GET`
* Endpoint: `/listed-room`
* Response:
- Status code:
+ `200 OK`
+ `401 Unauthorized` when the user is not logged in
- Header:
field | type | Description
------|------|------------
`searchTerm` | string | search term
- Data: See array definition in `Get user´s conversations`
## Rename a conversation
* Method: `PUT`
@ -156,8 +157,8 @@
## Set description for a conversation
* Required capability: `room-description`
* Method: `PUT`
* API: v3
* Endpoint: `/room/{token}/description`
* Data:
@ -199,6 +200,7 @@
## Set read-only for a conversation
* Required capability: `read-only-rooms`
* Method: `PUT`
* Endpoint: `/room/{token}/read-only`
* Data:
@ -283,12 +285,13 @@
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the the given level is invalid
+ `400 Bad Request` When the given level is invalid
+ `401 Unauthorized` When the participant is a guest
+ `404 Not Found` When the conversation could not be found for the participant
`userId` | string | v1 + v2 only | Is empty for guests
`attendeeId` | int | v3 | Unique attendee id
`actorType` | string | v3 | Currently known `users|guests|emails|groups`
`actorId` | string | v3 | The unique identifier for the given actor type
`displayName` | string | | Can be empty for guests
`participantType` | int | | Permissions level of the participant
`lastPing` | int | | Timestamp of the last ping of the user (should be used for sorting)
`sessionId` | string | | `'0'` if not connected, otherwise a 512 character long string
`status` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
`statusIcon` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
`statusMessage` | string | | Optional: Only available with `includeStatus=true` and for users with a set status
`displayName` | string | * | Can be empty for guests
`participantType` | int | * | Permissions level of the participant (see [constants list](constants.md#participant-types))
`lastPing` | int | * | Timestamp of the last ping of the user (should be used for sorting)
`inCall` | int | * | Call flags the user joined with (see [constants list](constants.md#participant-in-call-flag))
`sessionId` | string | * | `'0'` if not connected, otherwise a 512 character long string
`status` | string | * | 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 | * | 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 | * | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation
## Add a participant to a conversation
@ -87,7 +88,7 @@
## Delete a participant from a conversation
* API: Only `v1` and `v2`
* API: Only `v1` and `v2` (Use [Delete an attendee by id from a conversation](#delete-an-attendee-by-id-from-a-conversation) in later version)
* Method: `DELETE`
* Endpoint: `/room/{token}/participants`
* Data:
@ -119,7 +120,7 @@
## Remove a guest from a conversation
* API: Only `v1` and `v2`
* API: Only `v1` and `v2` (Use [Delete an attendee by id from a conversation](#delete-an-attendee-by-id-from-a-conversation) in later versions)
* Method: `DELETE`
* Endpoint: `/room/{token}/participants/guests`
* Data:
@ -154,11 +155,7 @@
+ `404 Not Found` When the conversation could not be found for the participant
+ `409 Conflict` When the user already has an active session in the conversation. 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`:
field | type | Description
------|------|------------
`sessionId` | string | 512 character long string
- Data in case of `200 OK`: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
`attachment_folder` | `config => attachments => folder` | `/Talk` | Path owned by the user to store uploads and received shares. It is created if it does not exist.
`read_status_privacy` | `config => chat => read-privacy` | `0` | One of the read-status constants from the [constants list](constants.md#Participant-read-status-privacy)
## Set SIP settings
* Required capability: `sip-support`
* Method: `POST`
* Endpoint: `/settings/sip`
* Data:
All values must be sent in the same request
field | type | Description
------|------|------------
`sipGroups` | array | List of group ids that are allow to enable SIP for a conversation
`dialInInfo` | string | The dial-in information shown in the sidebar and sent in emails
`sharedSecret` | string | The shared secret of the SIP component
@ -6,8 +6,11 @@ Group and public conversations can be used to host webinars. Those online meetin
* Only moderators can read and write chat messages
* Normal users can only join the room. They then pull the room endpoint regularly for an update and should start the chat and signaling as well as allowing to join the call, once the lobby got disabled.
## Base endpoint
Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
* Base endpoint for API v1 is: `/ocs/v2.php/apps/spreed/api/v1`
* Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
* Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
## Set lobby for a conversation
@ -29,6 +32,8 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+ `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: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
## Enabled or disable SIP dial-in
* Required capability: `sip-support`
@ -48,3 +53,5 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+ `403 Forbidden` When the current user is not a moderator/owner
+ `404 Not Found` When the conversation could not be found for the participant
+ `412 Precondition Failed` When SIP is not configured on the server
- Data: See array definition in [Get user´s conversations](conversation.md#get-user-s-conversations)
Joas Schilling
5 years ago