Update docs for conversations

Signed-off-by: Joas Schilling <coding@schilljs.com>

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