diff options
| -rw-r--r-- | docs/call-experience.md | 43 | ||||
| -rw-r--r-- | docs/call.md | 36 | ||||
| -rw-r--r-- | docs/chat.md | 210 | ||||
| -rw-r--r-- | docs/commands.md | 24 | ||||
| -rw-r--r-- | docs/conversation.md | 198 | ||||
| -rw-r--r-- | docs/integration.md | 40 | ||||
| -rw-r--r-- | docs/internal-signaling.md | 46 | ||||
| -rw-r--r-- | docs/participant.md | 118 | ||||
| -rw-r--r-- | docs/reaction.md | 54 | ||||
| -rw-r--r-- | docs/settings.md | 26 | ||||
| -rw-r--r-- | docs/webinar.md | 14 |
11 files changed, 403 insertions, 406 deletions
diff --git a/docs/call-experience.md b/docs/call-experience.md index e8f4fda7c..1a73c2ade 100644 --- a/docs/call-experience.md +++ b/docs/call-experience.md @@ -10,34 +10,33 @@ If a participant enabled their microphone and starts speaking the video quality ### Number of video streams -Streams | Quality ----|--- -< 4 | High -4-7 | Medium -8-10 | Low -11-14 | Very low -> 14 | Thumbnail - +| Streams | Quality | +|---------|-----------| +| < 4 | High | +| 4-7 | Medium | +| 8-10 | Low | +| 11-14 | Very low | +| > 14 | Thumbnail | ### Number of audio streams -Streams | Quality ----|--- -< 10 | High -10-19 | Medium -20-29 | Low -30-39 | Very low -> 40 | Thumbnail +| Streams | Quality | +|---------|-----------| +| < 10 | High | +| 10-19 | Medium | +| 20-29 | Low | +| 30-39 | Very low | +| > 40 | Thumbnail | ### Video qualities -Quality | Max width | Ideal width | Max height | Ideal height | Max frames | Ideal frames ----|---|---|---|---|---|--- -High | - | 720 | - | 540 | - | 30 -Medium | 640 | 560 | 480 | 420 | 24 | 24 -Low | 480 | 360 | 320 | 270 | 15 | 15 -Very low | 320 | - | 240 | - | 8 | - -Thumbnail | 320 | - | 240 | - | 1 | - +| Quality | Max width | Ideal width | Max height | Ideal height | Max frames | Ideal frames | +|-----------|-----------|-------------|------------|--------------|------------|--------------| +| High | - | 720 | - | 540 | - | 30 | +| Medium | 640 | 560 | 480 | 420 | 24 | 24 | +| Low | 480 | 360 | 320 | 270 | 15 | 15 | +| Very low | 320 | - | 240 | - | 8 | - | +| Thumbnail | 320 | - | 240 | - | 1 | - | ## Judging the connection quality diff --git a/docs/call.md b/docs/call.md index 92fadce89..f0a76c8a8 100644 --- a/docs/call.md +++ b/docs/call.md @@ -20,14 +20,14 @@ - Data: Array of participants, each participant has at least: - field | type | Added | Removed | Description - ---|---|---|---|--- - `actorType` | string | v3 | | Actor type of the attendee (see [Constants - Attendee types](constants.md#attendee-types)) - `actorId` | string | v3 | | The user id, guest random id or email address of the attendee - `userId` | string | v1 | v3 | The user id replaced with actorType = users and actorId being the userId - `displayName` | string | v3 | | The display name of the attendee - `lastPing` | int | v1 | | Timestamp of the last ping of the user (should be used for sorting) - `sessionId` | string | v1 | | 512 character long string +| field | type | Added | Removed | Description | +|---------------|--------|-------|---------|--------------------------------------------------------------------------------------------| +| `actorType` | string | v3 | | Actor type of the attendee (see [Constants - Attendee types](constants.md#attendee-types)) | +| `actorId` | string | v3 | | The user id, guest random id or email address of the attendee | +| `userId` | string | v1 | v3 | The user id replaced with actorType = users and actorId being the userId | +| `displayName` | string | v3 | | The display name of the attendee | +| `lastPing` | int | v1 | | Timestamp of the last ping of the user (should be used for sorting) | +| `sessionId` | string | v1 | | 512 character long string | ## Join a call @@ -35,10 +35,10 @@ * Endpoint: `/call/{token}` * Data: - field | type | Description - ---|---|--- - `flags` | int | Flags what streams are provided by the participant (see [Constants - Participant in-call flag](constants.md#participant-in-call-flag)) - `silent` | bool | Disable start call notifications for group/public calls +| field | type | Description | +|----------|------|----------------------------------------------------------------------------------------------------------------------------------------| +| `flags` | int | Flags what streams are provided by the participant (see [Constants - Participant in-call flag](constants.md#participant-in-call-flag)) | +| `silent` | bool | Disable start call notifications for group/public calls | * Response: - Status code: @@ -55,9 +55,9 @@ * Endpoint: `/call/{token}/ring/{attendeeId}` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int | The participant to notify +| field | type | Description | +|--------------|------|---------------------------| +| `attendeeId` | int | The participant to notify | * Response: - Status code: @@ -76,9 +76,9 @@ * Endpoint: `/call/{token}` * Data: - field | type | Description - ---|---|--- - `flags` | int | Flags what streams are provided by the participant (see [Constants - Participant in-call flag](constants.md#participant-in-call-flag)) +| field | type | Description | +|---------|------|----------------------------------------------------------------------------------------------------------------------------------------| +| `flags` | int | Flags what streams are provided by the participant (see [Constants - Participant in-call flag](constants.md#participant-in-call-flag)) | * Response: - Status code: diff --git a/docs/chat.md b/docs/chat.md index a47ea5522..ab01949df 100644 --- a/docs/chat.md +++ b/docs/chat.md @@ -8,15 +8,15 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 * Endpoint: `/chat/{token}` * Data: - field | type | Description - ---|---|--- - `lookIntoFuture` | int | `1` Poll and wait for new message or `0` get history of a conversation - `limit` | int | Number of chat messages to receive (100 by default, 200 at most) - `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header. - `lastCommonReadId` | int | Send the last `X-Chat-Last-Common-Read` header you got, if you are interested in updates of the common read value. A 304 response does not allow custom headers and otherwise the server can not know if your value is modified or not. - `timeout` | int | `$lookIntoFuture = 1` only, Number of seconds to wait for new messages (30 by default, 60 at most) - `setReadMarker` | int | `1` to automatically set the read timer after fetching the messages, use `0` when your client calls `Mark chat as read` manually. (Default: `1`) - `includeLastKnown` | int | `1` to include the last known message as well (Default: `0`) +| field | type | Description | +|----------------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `lookIntoFuture` | int | `1` Poll and wait for new message or `0` get history of a conversation | +| `limit` | int | Number of chat messages to receive (100 by default, 200 at most) | +| `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header. | +| `lastCommonReadId` | int | Send the last `X-Chat-Last-Common-Read` header you got, if you are interested in updates of the common read value. A 304 response does not allow custom headers and otherwise the server can not know if your value is modified or not. | +| `timeout` | int | `$lookIntoFuture = 1` only, Number of seconds to wait for new messages (30 by default, 60 at most) | +| `setReadMarker` | int | `1` to automatically set the read timer after fetching the messages, use `0` when your client calls `Mark chat as read` manually. (Default: `1`) | +| `includeLastKnown` | int | `1` to include the last known message as well (Default: `0`) | * Response: - Status code: @@ -27,40 +27,40 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 - Header: - field | type | Description - ---|---|--- - `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page. - `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 and when lastCommonReadId was sent) +| field | type | Description | +|---------------------------|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page. | +| `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 and when lastCommonReadId was sent) | - Data: Array of messages, each message has at least: - field | type | Description - ---|---|--- - `id` | int | ID of the comment - `token` | string | Conversation token - `actorType` | string | See [Constants - Actor types of chat messages](constants.md#actor-types-of-chat-messages) - `actorId` | string | Actor id of the message author - `actorDisplayName` | string | Display name of the message author - `timestamp` | int | Timestamp in seconds and UTC time zone - `systemMessage` | string | empty for normal chat message or the type of the system message (untranslated) - `messageType` | string | Currently known types are `comment`, `comment_deleted`, `system` and `command` - `isReplyable` | bool | True if the user can post a reply to this message (only available with `chat-replies` capability) - `referenceId` | string | A reference string that was given while posting the message to be able to identify a sent message again (only available with `chat-reference-id` capability) - `message` | string | Message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) - `messageParameters` | array | Message parameters for `message` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) - `parent` | array | **Optional:** See `Parent data` below - `reactions` | array | **Optional:** An array map with relation between reaction emoji and total count of reactions with this emoji - `reactionsSelf` | array | **Optional:** When the user reacted this is the list of emojis the user reacted with +| field | type | Description | +|---------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | int | ID of the comment | +| `token` | string | Conversation token | +| `actorType` | string | See [Constants - Actor types of chat messages](constants.md#actor-types-of-chat-messages) | +| `actorId` | string | Actor id of the message author | +| `actorDisplayName` | string | Display name of the message author | +| `timestamp` | int | Timestamp in seconds and UTC time zone | +| `systemMessage` | string | empty for normal chat message or the type of the system message (untranslated) | +| `messageType` | string | Currently known types are `comment`, `comment_deleted`, `system` and `command` | +| `isReplyable` | bool | True if the user can post a reply to this message (only available with `chat-replies` capability) | +| `referenceId` | string | A reference string that was given while posting the message to be able to identify a sent message again (only available with `chat-reference-id` capability) | +| `message` | string | Message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) | +| `messageParameters` | array | Message parameters for `message` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) | +| `parent` | array | **Optional:** See `Parent data` below | +| `reactions` | array | **Optional:** An array map with relation between reaction emoji and total count of reactions with this emoji | +| `reactionsSelf` | array | **Optional:** When the user reacted this is the list of emojis the user reacted with | #### Parent data * When deleted: - field | type | Description - ---|---|--- - `id` | int | ID of the parent comment - `deleted` | bool | `true` when the parent is deleted +| field | type | Description | +|-----------|------|-----------------------------------| +| `id` | int | ID of the parent comment | +| `deleted` | bool | `true` when the parent is deleted | * Regular message: @@ -73,13 +73,13 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 * Endpoint: `/chat/{token}` * Data: - field | type | Description - ---|---|--- - `message` | string | The message the user wants to say - `actorDisplayName` | string | Guest display name (ignored for logged in users) - `replyTo` | int | The message ID this message is a reply to (only allowed for messages from the same conversation and when the message type is not `system` or `command`) - `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) - `silent` | bool | If sent silent the message will not create chat notifications even for mentions (only available with `silent-send` capability) +| field | type | Description | +|--------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `message` | string | The message the user wants to say | +| `actorDisplayName` | string | Guest display name (ignored for logged in users) | +| `replyTo` | int | The message ID this message is a reply to (only allowed for messages from the same conversation and when the message type is not `system` or `command`) | +| `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) | +| `silent` | bool | If sent silent the message will not create chat notifications even for mentions (only available with `silent-send` capability) | * Response: - Status code: @@ -92,9 +92,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 - 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) +| 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) @@ -108,13 +108,13 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * 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) +| 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: @@ -127,9 +127,9 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob - 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) +| 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) @@ -140,19 +140,19 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * Endpoint: `ocs/v2.php/apps/files_sharing/api/v1/shares` * Data: - field | type | Description - ---|---|--- - `shareType` | int | `10` means share to a conversation - `shareWith` | string | The token of the conversation to share the file to - `path` | string | The file path inside the user's root to share - `referenceId` | string | A reference string to be able to identify the generated chat message again in a "get messages" request, should be a random sha256 (only available with `chat-reference-id` capability) - `talkMetaData` | string | JSON encoded array of the meta data +| field | type | Description | +|----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `shareType` | int | `10` means share to a conversation | +| `shareWith` | string | The token of the conversation to share the file to | +| `path` | string | The file path inside the user's root to share | +| `referenceId` | string | A reference string to be able to identify the generated chat message again in a "get messages" request, should be a random sha256 (only available with `chat-reference-id` capability) | +| `talkMetaData` | string | JSON encoded array of the meta data | -* `talkMetaData` array: + - `talkMetaData` array: - field | type | Description - ---|---|--- - `messageType` | string | A message type to show the message in different styles. Currently known: `voice-message` and `comment` +| field | type | Description | +|---------------|--------|--------------------------------------------------------------------------------------------------------| +| `messageType` | string | A message type to show the message in different styles. Currently known: `voice-message` and `comment` | * Response: [See official OCS Share API docs](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-share-api.html?highlight=sharing#create-a-new-share) @@ -163,9 +163,9 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * Endpoint: `/chat/{token}/share/overview` * Data: - field | type | Description - ---|---|--- - `limit` | int | Number of chat messages with shares you want to get +| field | type | Description | +|---------|------|-----------------------------------------------------| +| `limit` | int | Number of chat messages with shares you want to get | * Response: - Note: if a file was shared multiple times it will be returned multiple times @@ -185,11 +185,11 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * Endpoint: `/chat/{token}/share` * Data: - field | type | Description - ---|---|--- - `objectType` | string | One of the [Constants - Shared item types](constants.md#shared-item-types) - `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header. - `limit` | int | Number of chat messages with shares you want to get +| field | type | Description | +|----------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| +| `objectType` | string | One of the [Constants - Shared item types](constants.md#shared-item-types) | +| `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header. | +| `limit` | int | Number of chat messages with shares you want to get | * Response: - Note: if a file was shared multiple times it will be returned multiple times @@ -200,9 +200,9 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob - Header: - field | type | Description - ---|---|--- - `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page. +| field | type | Description | +|---------------------|------|------------------------------------------------| +| `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page. | - Data: Array of messages as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation) @@ -222,9 +222,9 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob - Header: - field | type | Description - --- |