Add documentation and capability

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

docs/capabilities.md

@@ -67,3 +67,4 @@ title: Capabilities
 
 ## 12.0
 * `delete-messages` - Allows to delete chat messages up to 6 hours for your own messages or when being a moderator. On deleting the message text will be replaced and a follow up system message will make sure clients and users update it in their cache and storage.
+* `rich-object-sharing` - Rich objects can be shared to chats. See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob/master/lib/public/RichObjectStrings/Definitions.php) for more details on supported rich objects and required data.

docs/chat.md

@@ -96,6 +96,40 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
     - Data:
         The full message array of the new message, as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation)
 
+## Share a rich object to the chat
+
+See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob/master/lib/public/RichObjectStrings/Definitions.php) for more details on supported rich objects and required data.
+
+* Required capability: `rich-object-sharing`
+* Method: `POST`
+* Endpoint: `/chat/{token}/share`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `objectType` | string | The object type
+    `objectId` | string | The object id
+    `metaData` | string | JSON encoded array of the rich objects data
+    `actorDisplayName` | string | Guest display name (ignored for logged in users)
+    `referenceId` | string | A reference string to be able to identify the message again in a "get messages" request, should be a random sha256 (only available with `chat-reference-id` capability)
+
+* Response:
+    - Status code:
+        + `201 Created`
+        + `400 Bad Request` In case the meta data is invalid
+        + `403 Forbidden` When the conversation is read-only
+        + `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
+        + `413 Payload Too Large` When the message was longer than the allowed limit of 32000 characters (or 1000 until Nextcloud 16.0.1, check the `spreed => config => chat => max-length` capability for the limit)
+
+    - Header:
+
+        field | type | Description
+        ------|------|------------
+        `X-Chat-Last-Common-Read` | int | ID of the last message read by every user that has read privacy set to public. When the user themself has it set to private the value the header is not set (only available with `chat-read-status` capability)
+
+    - Data:
+        The full message array of the new message, as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation)
 
 ## Deleting a chat message
 

lib/Capabilities.php

@@ -88,6 +88,7 @@ class Capabilities implements IPublicCapability {
 				'phonebook-search',
 				'raise-hand',
 				'room-description',
+				'rich-object-sharing',
 			],
 			'config' => [
 				'attachments' => [

tests/php/CapabilitiesTest.php

@@ -85,6 +85,7 @@ class CapabilitiesTest extends TestCase {
 			'phonebook-search',
 			'raise-hand',
 			'room-description',
+			'rich-object-sharing',
 		];
 	}