diff options
author | Joas Schilling <coding@schilljs.com> | 2019-10-10 11:57:29 +0300 |
---|---|---|
committer | Joas Schilling <coding@schilljs.com> | 2019-10-10 12:19:23 +0300 |
commit | 227dbb913253bb21bdac37b38c11df3dbc38b65c (patch) | |
tree | 62bd14c75745d86f82218a3cddf17b5a8f084825 /docs | |
parent | 3b90447cd9599faebdf1c90eefa96ff429cb021f (diff) |
Update docs for conversations
Signed-off-by: Joas Schilling <coding@schilljs.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/constants.md | 6 | ||||
-rw-r--r-- | docs/conversation.md | 134 |
2 files changed, 77 insertions, 63 deletions
diff --git a/docs/constants.md b/docs/constants.md index 8cd7c5ee0..6192ab678 100644 --- a/docs/constants.md +++ b/docs/constants.md @@ -26,6 +26,12 @@ title: Constants * `2` provides audio * `4` provides video +## Participant notification levels +* `0` Default (`1` for one-to-one conversations, `2` for other conversations) +* `1` Always notify +* `2` Notify on mention +* `4` Never notify + ## Actor types of chat messages * `guests` - guest users * `users` - logged-in users diff --git a/docs/conversation.md b/docs/conversation.md index cee3b2f46..7de20a04d 100644 --- a/docs/conversation.md +++ b/docs/conversation.md @@ -2,34 +2,6 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` -## Creating a new conversation - -* Method: `POST` -* Endpoint: `/room` -* Data: - - field | type | Description - ------|------|------------ - `roomType` | int | - `invite` | string | user id (`roomType = 1`), group id (`roomType = 2` - optional) - `roomName` | string | conversation name (Not available for `roomType = 1`) - -* Response: - - Header: - + `200 OK` when the "one to one" conversation already exists - + `201 Created` when the conversation was created - + `400 Bad Request` when an invalid conversation type was given - + `401 Unauthorized` when the user is not logged in - + `404 Not Found` when the user or group does not exist - - - Data: - - field | type | Description - ------|------|------------ - `token` | string | Token identifier of the conversation which is used for further interaction - `name` | string | Name of the conversation (can also be empty) - `displayName` | string | `name` if non empty, otherwise it falls back to a list of participants - ## Get userĀ“s conversations * Method: `GET` @@ -71,7 +43,36 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` `lastMessage` | message | Last message in a conversation if available, otherwise empty `objectType` | string | The type of object that the conversation is associated with; "share:password" if the conversation is used to request a password for a share, otherwise empty `objectId` | string | Share token if "objectType" is "share:password", otherwise empty - + +## Creating a new conversation + +* Method: `POST` +* Endpoint: `/room` +* Data: + + field | type | Description + ------|------|------------ + `roomType` | int | + `invite` | string | user id (`roomType = 1`), group id (`roomType = 2` - optional) + `roomName` | string | conversation name (Not available for `roomType = 1`) + +* Response: + - Header: + + `200 OK` When the "one to one" conversation already exists + + `201 Created` When the conversation was created + + `400 Bad Request` When an invalid conversation type was given + + `400 Bad Request` When the conversation name is empty for `type = 3` + + `401 Unauthorized` When the user is not logged in + + `404 Not Found` When the target to invite does not exist + + - Data: + + field | type | Description + ------|------|------------ + `token` | string | Token identifier of the conversation which is used for further interaction + `name` | string | Name of the conversation (can also be empty) + `displayName` | string | `name` if non empty, otherwise it falls back to a list of participants + ## Get single conversation (also for guests) * Method: `GET` @@ -98,74 +99,78 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` - Header: + `200 OK` + `400 Bad Request` When the name is too long or empty + + `400 Bad Request` When the conversation is a one to one conversation + `403 Forbidden` When the current user is not a moderator/owner + `404 Not Found` When the conversation could not be found for the participant - + `405 Method Not Allowed` When the conversation is a one to one conversation -## Set read-only for a conversation - -* Method: `PUT` -* Endpoint: `/room/{token}/read-only` -* Data: +## Delete a conversation - field | type | Description - ------|------|------------ - `state` | int | New state for the conversation +* Method: `DELETE` +* Endpoint: `/room/{token}` * Response: - Header: + `200 OK` - + `400 Bad Request` When the conversation type does not support read-only (only group and public conversation atm) - + `403 Forbidden` When the current user is not a moderator/owner or the conversation is not a public conversation + + `400 Bad Request` When the conversation is a one-to-one conversation (Use [Remove yourself from a conversation](participant.md#Remove-yourself-from-a-conversation) instead) + + `403 Forbidden` When the current user is not a moderator/owner + `404 Not Found` When the conversation could not be found for the participant -## Set password for a conversation - -* Method: `PUT` -* Endpoint: `/room/{token}/password` -* Data: +## Allow guests in a conversation (public conversation) - field | type | Description - ------|------|------------ - `password` | string | New password for the conversation +* Method: `POST` +* Endpoint: `/room/{token}/public` * Response: - Header: + `200 OK` - + `403 Forbidden` When the current user is not a moderator/owner or the conversation is not a public conversation + + `400 Bad Request` When the conversation is not a group conversation + + `403 Forbidden` When the current user is not a moderator/owner + `404 Not Found` When the conversation could not be found for the participant -## Delete a conversation +## Disallow guests in a conversation (group conversation) * Method: `DELETE` -* Endpoint: `/room/{token}` +* Endpoint: `/room/{token}/public` * Response: - Header: + `200 OK` + + `400 Bad Request` When the conversation is not a public conversation + `403 Forbidden` When the current user is not a moderator/owner + `404 Not Found` When the conversation could not be found for the participant -## Allow guests in a conversation (public conversation) +## Set read-only for a conversation -* Method: `POST` -* Endpoint: `/room/{token}/public` +* Method: `PUT` +* Endpoint: `/room/{token}/read-only` +* Data: + + field | type | Description + ------|------|------------ + `state` | int | New state for the conversation * Response: - Header: + `200 OK` - + `403 Forbidden` When the current user is not a moderator/owner + + `400 Bad Request` When the conversation type does not support read-only (only group and public conversation) + + `403 Forbidden` When the current user is not a moderator/owner or the conversation is not a public conversation + `404 Not Found` When the conversation could not be found for the participant -## Disallow guests in a conversation (group conversation) +## Set password for a conversation -* Method: `DELETE` -* Endpoint: `/room/{token}/public` +* Method: `PUT` +* Endpoint: `/room/{token}/password` +* Data: + + field | type | Description + ------|------|------------ + `password` | string | New password for the conversation * Response: - Header: + `200 OK` - + `403 Forbidden` When the current user is not a moderator/owner + + `403 Forbidden` When the current user is not a moderator or owner + + `403 Forbidden` When the conversation is not a public conversation + `404 Not Found` When the conversation could not be found for the participant ## Set conversation password @@ -193,7 +198,8 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` * Response: - Header: + `200 OK` - + `404 Not Found` When the conversation could not be found for the participant or the participant is a guest + + `401 Unauthorized` When the participant is a guest + + `404 Not Found` When the conversation could not be found for the participant ## Remove conversation from favorites @@ -203,7 +209,8 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` * Response: - Header: + `200 OK` - + `404 Not Found` When the conversation could not be found for the participant or the participant is a guest + + `401 Unauthorized` When the participant is a guest + + `404 Not Found` When the conversation could not be found for the participant ## Set notification level @@ -213,10 +220,11 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1` field | type | Description ------|------|------------ - `level` | int | The notification level (one of `Participant::NOTIFY_*` (1-3)) + `level` | int | The notification level (See [Participant notification levels](constants.md#Participant-notification-levels)) * Response: - Header: + `200 OK` + `400 Bad Request` When the the given level is invalid - + `404 Not Found` When the conversation could not be found for the participant or the participant is a guest + + `401 Unauthorized` When the participant is a guest + + `404 Not Found` When the conversation could not be found for the participant |