diff options
| author | Joas Schilling <coding@schilljs.com> | 2022-07-01 11:45:07 +0300 |
|---|---|---|
| committer | Joas Schilling <coding@schilljs.com> | 2022-07-01 18:29:24 +0300 |
| commit | 1ec6a4f40d103186632ae62ece95f0b91db3ab0c (patch) | |
| tree | e4f48ee6084e482203ddfbf297675734260cc6fc | |
| parent | 332352f40af5fdf63ed6e877e391704ea0290e40 (diff) | |
Fix table structures so IDEs stop complaining even though it is valid markdown
Signed-off-by: Joas Schilling <coding@schilljs.com>
| -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 - ---|---|--- - `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 system message "You cleared the history of the conversation", as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation) @@ -250,9 +250,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 system message "You deleted a message", as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation) @@ -267,9 +267,9 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * Endpoint: `/chat/{token}/read` * Data: - field | type | Description - ---|---|--- - `lastReadMessage` | int | The last read message ID +| field | type | Description | +|-------------------|------|--------------------------| +| `lastReadMessage` | int | The last read message ID | * Response: - Status code: @@ -279,10 +279,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) | ## Mark chat as unread @@ -298,10 +297,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) | ## Get mention autocomplete suggestions @@ -309,11 +307,11 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob * Endpoint: `/chat/{token}/mentions` * Data: - field | type | Description - ---|---|--- - `search` | string | Search term for name suggestions (should at least be 1 character) - `limit` | int | Number of suggestions to receive (20 by default) - `includeStatus` | bool | Whether the user status information also needs to be loaded +| field | type | Description | +|-----------------|--------|-------------------------------------------------------------------| +| `search` | string | Search term for name suggestions (should at least be 1 character) | +| `limit` | int | Number of suggestions to receive (20 by default) | +| `includeStatus` | bool | Whether the user status information also needs to be loaded | * Response: - Status code: @@ -325,14 +323,14 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob - Data: Array of suggestions, each suggestion has at least: - field | type | Description - ---|---|--- - `id` | string | The user id which should be sent as `@<id>` in the message (user ids that contain spaces as well as guest ids need to be wrapped in double-quotes when sending in a message: `@"space user"` and `@"guest/random-string"`) - `label` | string | The displayname of the user - `source` | string | The type of the user, currently only `users`, `guests` or `calls` (for mentioning the whole conversation - `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 +| field | type | Description | +|-----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | The user id which should be sent as `@<id>` in the message (user ids that contain spaces as well as guest ids need to be wrapped in double-quotes when sending in a message: `@"space user"` and `@"guest/random-string"`) | +| `label` | string | The displayname of the user | +| `source` | string | The type of the user, currently only `users`, `guests` or `calls` (for mentioning the whole conversation | +| `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 | ## System messages diff --git a/docs/commands.md b/docs/commands.md index 8d33e7155..3aca4e063 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -11,21 +11,21 @@ ## "Add command" arguments -Argument | Allowed chars | Description ----|---|--- -`cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters) -`name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters) -`script` | * | Actual command that is being ran. The script must be executable by the user of your webserver and has to use absolute paths only! See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly. -`response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone -`enabled` | 0-3 | Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone +| Argument | Allowed chars | Description | +|------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters) | +| `name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters) | +| `script` | * | Actual command that is being ran. The script must be executable by the user of your webserver and has to use absolute paths only! See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly. | +| `response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone | +| `enabled` | 0-3 | Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone | ## Script parameter -Parameter | Description ----|--- -`{ROOM}` | The token of the room the command was used in -`{USER}` | ID of the user that called the command -`{ARGUMENTS}` | Everything the user write after the actual command +| Parameter | Description | +|---------------|----------------------------------------------------| +| `{ROOM}` | The token of the room the command was used in | +| `{USER}` | ID of the user that called the command | +| `{ARGUMENTS}` | Everything the user write after the actual command | ## Example diff --git a/docs/conversation.md b/docs/conversation.md index fcc9aa0fe..5e668207c 100644 --- a/docs/conversation.md +++ b/docs/conversation.md @@ -11,10 +11,10 @@ * Endpoint: `/room` * Data: - field | type | Description - ---|---|--- - `noStatusUpdate` | int | Whether the "online" user status of the current user should be "kept-alive" (`1`) or not (`0`) (defaults to `0`) - `includeStatus` | bool | Whether the user status information of all one-to-one conversations should be loaded (default false) +| field | type | Description | +|------------------|------|------------------------------------------------------------------------------------------------------------------| +| `noStatusUpdate` | int | Whether the "online" user status of the current user should be "kept-alive" (`1`) or not (`0`) (defaults to `0`) | +| `includeStatus` | bool | Whether the user status information of all one-to-one conversations should be loaded (default false) | * Response: - Status code: @@ -23,65 +23,65 @@ - Header: - field | type | Description - ---|---|--- - `X-Nextcloud-Talk-Hash` | string | Sha1 value over some config. When you receive a different value on subsequent requests, the capabilities and the signaling settings should be refreshed. +| field | type | Description | +|-------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `X-Nextcloud-Talk-Hash` | string | Sha1 value over some config. When you receive a different value on subsequent requests, the capabilities and the signaling settings should be refreshed. | - Data: Array of conversations, each conversation has at least: - field | type | Added | Removed | Description - ---|---|---|---|--- - `id` | int | v1 | | Numeric identifier of the conversation - `token` | string | v1 | | Token identifier of the conversation which is used for further interaction - `type` | int | v1 | | See list of conversation types in the [constants list](constants.md#conversation-types) - `name` | string | v1 | | Name of the conversation (can also be empty) - `displayName` | string | v1 | | `name` if non empty, otherwise it falls back to a list of participants - `description` | string | v3 | | Description of the conversation (can also be empty) (only available with `room-description` capability) - `participantType` | int | v1 | | Permissions level of the current user - `attendeeId` | int | v3 | | Unique attendee id - `attendeePin` | string | v3 | | Unique dial-in authentication code for this user, when the conversation has SIP enabled (see `sipEnabled` attribute) - `actorType` | string | v3 | | Currently known `users|guests|emails|groups|circles` - `actorId` | string | v3 | | The unique identifier for the given actor type - `permissions` | int | v4 | | Combined final permissions for the current participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions)) - `attendeePermissions` | int | v4 | | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions)) - `callPermissions` | int | v4 | | Call permissions, if not `Custom` this are not the resulting permissions, if set they will reset after the end of the call (see [constants list](constants.md#attendee-permissions)) - `defaultPermissions` | int | v4 | | Default permissions for new participants (see [constants list](constants.md#attendee-permissions)) - `participantInCall` | bool | v1 | v2 | **Removed:** use `participantFlags` instead - `participantFlags` | int | v1 | | "In call" flags of the user's session making the request (only available with `in-call-flags` capability) - `readOnly` | int | v1 | | Read-only state for the current user (only available with `read-only-rooms` capability) - `listable` | int | v3 | | Listable scope for the room (only available with `listable-rooms` capability) - `messageExpiration` | int | v4 | | The message expiration time in seconds in this chat. Zero if disabled. (only available with `message-expiration` capability) - `count` | int | v1 | v2 | **Removed:** Count the users on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoint - `numGuests` | int | v1 | v2 | **Removed:** Count the guests on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoin - `lastPing` | int | v1 | | Timestamp of the user's session making the request - `sessionId` | string | v1 | | `'0'` if not connected, otherwise an up to 512 character long string that is the identifier of the user's session making the request. Should only be used to pre-check if the user joined already with this session, but this might be outdated by the time of usage, so better check via [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) - `hasPassword` | bool | v1 | | Flag if the conversation has a password - `hasCall` | bool | v1 | | 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 | v1 | | 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) - `lastActivity` | int | v1 | | Timestamp of the last activity in the conversation, in seconds and UTC time zone - `isFavorite` | bool | v1 | | Flag if the conversation is favorited by the user - `notificationLevel` | int | v1 | | The notification level for the user (See [Participant notification levels](constants.md#Participant-notification-levels)) - `lobbyState` | int | v1 | | Webinar lobby restriction (0-1), if the participant is a moderator they can always join the conversation (only available with `webinary-lobby` capability) (See [Webinar lobby states](constants.md#webinar-lobby-states)) - `lobbyTimer` | int | v1 | | Timestamp when the lobby will be automatically disabled (only available with `webinary-lobby` capability) - `sipEnabled` | int | v3 | | SIP enable status (see [constants list](constants.md#sip-states)) - `canEnableSIP` | int | v3 | | Whether the given user can enable SIP for this conversation. Note that when the token is not-numeric only, SIP can not be enabled even if the user is permitted and a moderator of the conversation - `unreadMessages` | int | v1 | | Number of unread chat messages in the conversation (only available with `chat-v2` capability) - `unreadMention` | bool | v1 | | Flag if the user was mentioned since their last visit - `unreadMentionDirect` | bool | v4 | | Flag if the user was mentioned directly (ignoring @all mentions) since their last visit (only available with `direct-mention-flag` capability) - `lastReadMessage` | int | v1 | | ID of the last read message in a room (only available with `chat-read-marker` capability) - `lastCommonReadMessage` | int | v3 | | ID of the last message read by every user that has read privacy set to public in a room. When the user themself has it set to private the value is `0` (only available with `chat-read-status` capability) - `lastMessage` | message | v1 | | Last message in a conversation if available, otherwise empty. **Note:** Even when given the message will not contain the `parent` or `reactionsSelf` attribute due to performance reasons - `objectType` | string | v1 | | 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 | v1 | | Share token if "objectType" is "share:password", otherwise empty - `status` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set - `statusIcon` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set - `statusMessage` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set - `participants` | array | v1 | v2 | **Removed** - `guestList` | string | v1 | v2 | **Removed** +| field | type | Added | Removed | Description | +|-------------------------|---------|-------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | int | v1 | | Numeric identifier of the conversation | +| `token` | string | v1 | | Token identifier of the conversation which is used for further interaction | +| `type` | int | v1 | | See list of conversation types in the [constants list](constants.md#conversation-types) | +| `name` | string | v1 | | Name of the conversation (can also be empty) | +| `displayName` | string | v1 | | `name` if non empty, otherwise it falls back to a list of participants | +| `description` | string | v3 | | Description of the conversation (can also be empty) (only available with `room-description` capability) | +| `participantType` | int | v1 | | Permissions level of the current user | +| `attendeeId` | int | v3 | | Unique attendee id | +| `attendeePin` | string | v3 | | Unique dial-in authentication code for this user, when the conversation has SIP enabled (see `sipEnabled` attribute) | +| `actorType` | string | v3 | | Currently known `users |guests|emails|groups|circles` +| `actorId` | string | v3 | | The unique identifier for the given actor type | +| `permissions` | int | v4 | | Combined final permissions for the current participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions)) | +| `attendeePermissions` | int | v4 | | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions)) | +| `callPermissions` | int | v4 | | Call permissions, if not `Custom` this are not the resulting permissions, if set they will reset after the end of the call (see [constants list](constants.md#attendee-permissions)) | +| `defaultPermissions` | int | v4 | | Default permissions for new participants (see [constants list](constants.md#attendee-permissions)) | +| `participantInCall` | bool | v1 | v2 | **Removed:** use `participantFlags` instead | +| `participantFlags` | int | v1 | | "In call" flags of the user's session making the request (only available with `in-call-flags` capability) | +| `readOnly` | int | v1 | | Read-only state for the current user (only available with `read-only-rooms` capability) | +| `listable` | int | v3 | | Listable scope for the room (only available with `listable-rooms` capability) | +| `messageExpiration` | int | v4 | | The message expiration time in seconds in this chat. Zero if disabled. (only available with `message-expiration` capability) | +| `count` | int | v1 | v2 | **Removed:** Count the users on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoint | +| `numGuests` | int | v1 | v2 | **Removed:** Count the guests on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoin | +| `lastPing` | int | v1 | | Timestamp of the user's session making the request | +| `sessionId` | string | v1 | | `'0'` if not connected, otherwise an up to 512 character long string that is the identifier of the user's session making the request. Should only be used to pre-check if the user joined already with this session, but this might be outdated by the time of usage, so better check via [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) | +| `hasPassword` | bool | v1 | | Flag if the conversation has a password | +| `hasCall` | bool | v1 | | 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 | v1 | | 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) | +| `lastActivity` | int | v1 | | Timestamp of the last activity in the conversation, in seconds and UTC time zone | +| `isFavorite` | bool | v1 | | Flag if the conversation is favorited by the user | +| `notificationLevel` | int | v1 | | The notification level for the user (See [Participant notification levels](constants.md#Participant-notification-levels)) | +| `lobbyState` | int | v1 | | Webinar lobby restriction (0-1), if the participant is a moderator they can always join the conversation (only available with `webinary-lobby` capability) (See [Webinar lobby states](constants.md#webinar-lobby-states)) | +| `lobbyTimer` | int | v1 | | Timestamp when the lobby will be automatically disabled (only available with `webinary-lobby` capability) | +| `sipEnabled` | int | v3 | | SIP enable status (see [constants list](constants.md#sip-states)) | +| `canEnableSIP` | int | v3 | | Whether the given user can enable SIP for this conversation. Note that when the token is not-numeric only, SIP can not be enabled even if the user is permitted and a moderator of the conversation | +| `unreadMessages` | int | v1 | | Number of unread chat messages in the conversation (only available with `chat-v2` capability) | +| `unreadMention` | bool | v1 | | Flag if the user was mentioned since their last visit | +| `unreadMentionDirect` | bool | v4 | | Flag if the user was mentioned directly (ignoring @all mentions) since their last visit (only available with `direct-mention-flag` capability) | +| `lastReadMessage` | int | v1 | | ID of the last read message in a room (only available with `chat-read-marker` capability) | +| `lastCommonReadMessage` | int | v3 | | ID of the last message read by every user that has read privacy set to public in a room. When the user themself has it set to private the value is `0` (only available with `chat-read-status` capability) | +| `lastMessage` | message | v1 | | Last message in a conversation if available, otherwise empty. **Note:** Even when given the message will not contain the `parent` or `reactionsSelf` attribute due to performance reasons | +| `objectType` | string | v1 | | 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 | v1 | | Share token if "objectType" is "share:password", otherwise empty | +| `status` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set | +| `statusIcon` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set | +| `statusMessage` | string | v4 | | Optional: Only available for one-to-one conversations and when `includeStatus=true` is set | +| `participants` | array | v1 | v2 | **Removed** | +| `guestList` | string | v1 | v2 | **Removed** | ## Creating a new conversation @@ -89,12 +89,12 @@ * Endpoint: `/room` * Data: - field | type | Description - ---|---|--- - `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`) +| field | type | Description | +|------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `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`) | * Response: - Status code: @@ -119,9 +119,9 @@ - Header: - field | type | Description - ---|---|--- - `X-Nextcloud-Talk-Hash` | string | Sha1 value over some config. When you receive a different value on subsequent requests, the capabilities and the signaling settings should be refreshed. +| field | type | Description | +|-------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `X-Nextcloud-Talk-Hash` | string | Sha1 value over some config. When you receive a different value on subsequent requests, the capabilities and the signaling settings should be refreshed. | - Data: See array definition in `Get user´s conversations` @@ -138,9 +138,9 @@ - Header: - field | type | Description - ---|---|--- - `searchTerm` | string | search term +| field | type | Description | +|--------------|--------|-------------| +| `searchTerm` | string | search term | - Data: See array definition in `Get user´s conversations` @@ -150,9 +150,9 @@ * Endpoint: `/room/{token}` * Data: - field | type | Description - ---|---|--- - `roomName` | string | New name for the conversation (1-200 characters) +| field | type | Description | +|------------|--------|--------------------------------------------------| +| `roomName` | string | New name for the conversation (1-200 characters) | * Response: - Status code: @@ -181,9 +181,9 @@ * Endpoint: `/room/{token}/description` * Data: - field | type | Description - ---|---|--- - `description` | string | New description for the conversation +| field | type | Description | +|---------------|--------|--------------------------------------| +| `description` | string | New description for the conversation | * Response: - Status code: @@ -224,9 +224,9 @@ * Endpoint: `/room/{token}/read-only` * Data: - field | type | Description - ---|---|--- - `state` | int | New state for the conversation, see [constants list](constants.md#read-only-states) +| field | type | Description | +|---------|------|-------------------------------------------------------------------------------------| +| `state` | int | New state for the conversation, see [constants list](constants.md#read-only-states) | * Response: - Status code: @@ -241,9 +241,9 @@ * Endpoint: `/room/{token}/password` * Data: - field | type | Description - ---|---|--- - `password` | string | New password for the conversation +| field | type | Description | +|------------|--------|-----------------------------------| +| `password` | string | New password for the conversation | * Response: - Status code: @@ -264,10 +264,10 @@ * Endpoint: `/room/{token}/permissions/{mode}` * Data: - field | type | Description - ---|---|--- - `mode` | string | `default` or `call`, in case of call the permissions will be reset to `0` (default) after the end of a call. - `permissions` | int | New permissions for the attendees, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. Note that this will reset all custom permissions that have been given to attendees so far. +| field | type | Description | +|---------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `mode` | string | `default` or `call`, in case of call the permissions will be reset to `0` (default) after the end of a call. | +| `permissions` | int | New permissions for the attendees, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. Note that this will reset all custom permissions that have been given to attendees so far. | * Response: - Status code: @@ -308,9 +308,9 @@ * Endpoint: `/room/{token}/notify` * Data: - field | type | Description - ---|---|--- - `level` | int | The notification level (See [Participant notification levels](constants.md#Participant-notification-levels)) +| field | type | Description | +|---------|------|--------------------------------------------------------------------------------------------------------------| +| `level` | int | The notification level (See [Participant notification levels](constants.md#Participant-notification-levels)) | * Response: - Status code: @@ -326,9 +326,9 @@ * Endpoint: `/room/{token}/notify-calls` * Data: - field | type | Description - ---|---|--- - `level` | int | The call notification level (See [Participant call notification levels](constants.md#Participant-call-notification-levels)) +| field | type | Description | +|---------|------|-----------------------------------------------------------------------------------------------------------------------------| +| `level` | int | The call notification level (See [Participant call notification levels](constants.md#Participant-call-notification-levels)) | * Response: - Status code: @@ -344,9 +344,9 @@ * Endpoint: `/room/{token}/message-expiration` * Data: - field | type | Description - ---|---|--- - `seconds` | int | The messages expiration in seconds. If is zero, messages will not be deleted automatically. +| field | type | Description | +|-----------|------|---------------------------------------------------------------------------------------------| +| `seconds` | int | The messages expiration in seconds. If is zero, messages will not be deleted automatically. | * Response: - Status code: @@ -362,9 +362,9 @@ * Endpoint: `/room/{token}/listable` * Data: - field | type | Description - ---|---|--- - `scope` | int | New flags for the conversation +| field | type | Description | +|---------|------|--------------------------------| +| `scope` | int | New flags for the conversation | * Response: - Status code: diff --git a/docs/integration.md b/docs/integration.md index 84598ce4b..a3416fd65 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -8,9 +8,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 * Endpoint: `/file/{fileId}` * Data: - field | type | Description - ---|---|--- - `fileId` | int | File id for which the conversation should be given +| field | type | Description | +|----------|------|----------------------------------------------------| +| `fileId` | int | File id for which the conversation should be given | * Response: - Status code: @@ -22,9 +22,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 - Data: - field | type | Description - ---|---|--- - `token` | string | The token of the conversation for this file +| field | type | Description | +|---------|--------|---------------------------------------------| +| `token` | string | The token of the conversation for this file | ## Get conversation for a public share @@ -32,9 +32,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 * Endpoint: `/publicshare/{shareToken}` * Data: - field | type | Description - ---|---|--- - `shareToken` | string | Share token for which the conversation should be given +| field | type | Description | +|--------------|--------|--------------------------------------------------------| +| `shareToken` | string | Share token for which the conversation should be given | * Response: - Status code: @@ -45,9 +45,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 - Data: - field | type | Description - ---|---|--- - `token` | string | The token of the conversation for this file +| field | type | Description | +|---------|--------|---------------------------------------------| +| `token` | string | The token of the conversation for this file | ## Create a conversation to request the password for a public share @@ -55,9 +55,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 * Endpoint: `/publicshareauth` * Data: - field | type | Description - ---|---|--- - `shareToken` | string | Share token for which the conversation should be given +| field | type | Description | +|--------------|--------|--------------------------------------------------------| +| `shareToken` | string | Share token for which the conversation should be given | * Response: - Status code: @@ -67,8 +67,8 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 15 - Data: - field | type | Description - ---|---|--- - `token` | string | The token of the conversation for this file - `name` | string | A technical name for the conversation - `displayName` | string | The visual name of the conversation +| field | type | Description | +|---------------|--------|---------------------------------------------| +| `token` | string | The token of the conversation for this file | +| `name` | string | A technical name for the conversation | +| `displayName` | string | The visual name of the conversation | diff --git a/docs/internal-signaling.md b/docs/internal-signaling.md index 8bdf3830b..fc75d4e29 100644 --- a/docs/internal-signaling.md +++ b/docs/internal-signaling.md @@ -10,36 +10,36 @@ * Endpoint: `/signaling/settings` * Data: - field | type | Description - ---|---|--- - `token` | string | The conversation to get the signaling settings for +| field | type | Description | +|---------|--------|----------------------------------------------------| +| `token` | string | The conversation to get the signaling settings for | * Response: - field | type | Added | Description - ---|---|---|--- - `signalingMode` | string | v1 | See [Signaling modes](constants.md#Signaling_modes) - `userId` | string | v1 | Current user id - `hideWarning` | string | v1 | Don't show a performance warning although internal signaling is used - `server` | string | v1 | URL of the external signaling server - `ticket` | string | v1 | Ticket for the external signaling server - `stunservers` | array | v3 | STUN servers - `turnservers` | array | v3 | TURN servers - `sipDialinInfo` | string | v2 | Generic SIP dial-in information for this conversation (admin free text containing the phone number etc) +| field | type | Added | Description | +|-----------------|--------|-------|---------------------------------------------------------------------------------------------------------| +| `signalingMode` | string | v1 | See [Signaling modes](constants.md#Signaling_modes) | +| `userId` | string | v1 | Current user id | +| `hideWarning` | string | v1 | Don't show a performance warning although internal signaling is used | +| `server` | string | v1 | URL of the external signaling server | +| `ticket` | string | v1 | Ticket for the external signaling server | +| `stunservers` | array | v3 | STUN servers | +| `turnservers` | array | v3 | TURN servers | +| `sipDialinInfo` | string | v2 | Generic SIP dial-in information for this conversation (admin free text containing the phone number etc) | - STUN server - - field | type | Description - ------|------|------------ - `urls` | array | Each element is a STUN server URL as a string + +| field | type | Description | +|--------|-------|-----------------------------------------------| +| `urls` | array | Each element is a STUN server URL as a string | - TURN server - - field | type | Description - ------|------|------------ - `urls` | array | Each element is a TURN server URL as a string - `username` | string | User name for the TURN server - `credential` | string | User password for the TURN server + +| field | type | Description | +|--------------|--------|-----------------------------------------------| +| `urls` | array | Each element is a TURN server URL as a string | +| `username` | string | User name for the TURN server | +| `credential` | string | User password for the TURN server | * Response: - Status code: diff --git a/docs/participant.md b/docs/participant.md index 94fa40650..5bf498900 100644 --- a/docs/participant.md +++ b/docs/participant.md @@ -11,9 +11,9 @@ * Endpoint: `/room/{token}/participants` * Data: - field | type | Description - ---|---|--- - `includeStatus` | bool | Whether the user status information also needs to be loaded +| field | type | Description | +|-----------------|------|-------------------------------------------------------------| +| `includeStatus` | bool | Whether the user status information also needs to be loaded | * Response: - Status code: @@ -25,22 +25,22 @@ - Data: Array of participants, each participant has at least: - field | type | Added | Removed | Description - ---|---|---|---|--- - `attendeeId` | int | v3 | | Unique attendee id - `actorType` | string | v3 | | Currently known `users|guests|emails|groups|circles` - `actorId` | string | v3 | | The unique identifier for the given actor type - `displayName` | string | v1 | | Can be empty for guests - `participantType` | int | v1 | | Permissions level of the participant (see [constants list](constants.md#participant-types)) - `lastPing` | int | v1 | | Timestamp of the last ping of the user (should be used for sorting) - `inCall` | int | v1 | | Call flags the user joined with (see [constants list](constants.md#participant-in-call-flag)) - `permissions` | int | v4 | | Combined final permissions for the participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions)) - `attendeePermissions` | int | v4 | | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions)) - `sessionId` | string | v1 | v4 | `'0'` if not connected, otherwise a 512 character long string - `sessionIds` | array | v4 | | array of session ids, each are 512 character long strings, or empty if no session - `status` | string | v2 | | 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 | v2 | | 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 | v2 | | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation +| field | type | Added | Removed | Description | +|-----------------------|--------|-------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `attendeeId` | int | v3 | | Unique attendee id | +| `actorType` | string | v3 | | Currently known `users |guests|emails|groups|circles` +| `actorId` | string | v3 | | The unique identifier for the given actor type | +| `displayName` | string | v1 | | Can be empty for guests | +| `participantType` | int | v1 | | Permissions level of the participant (see [constants list](constants.md#participant-types)) | +| `lastPing` | int | v1 | | Timestamp of the last ping of the user (should be used for sorting) | +| `inCall` | int | v1 | | Call flags the user joined with (see [constants list](constants.md#participant-in-call-flag)) | +| `permissions` | int | v4 | | Combined final permissions for the participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions)) | +| `attendeePermissions` | int | v4 | | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions)) | +| `sessionId` | string | v1 | v4 | `'0'` if not connected, otherwise a 512 character long string | +| `sessionIds` | array | v4 | | array of session ids, each are 512 character long strings, or empty if no session | +| `status` | string | v2 | | 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 | v2 | | 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 | v2 | | 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 @@ -48,10 +48,10 @@ * Endpoint: `/room/{token}/participants` * Data: - field | type | Description - ---|---|--- - `newParticipant` | string | User, group, email or circle to add - `source` | string | Source of the participant(s) as returned by the autocomplete suggestion endpoint (default is `users`) +| field | type | Description | +|------------------|--------|-------------------------------------------------------------------------------------------------------| +| `newParticipant` | string | User, group, email or circle to add | +| `source` | string | Source of the participant(s) as returned by the autocomplete suggestion endpoint (default is `users`) | * Response: - Status code: @@ -64,9 +64,9 @@ - Data: - field | type | Description - ---|---|--- - `type` | int | In case the conversation type changed, the new value is returned +| field | type | Description | +|--------|------|------------------------------------------------------------------| +| `type` | int | In case the conversation type changed, the new value is returned | ## Delete an attendee by id from a conversation @@ -74,9 +74,9 @@ * Endpoint: `/room/{token}/attendees` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int | The participant to delete +| field | type | Description | +|--------------|------|---------------------------| +| `attendeeId` | int | The participant to delete | * Response: - Status code: @@ -105,10 +105,10 @@ * Endpoint: `/room/{token}/participants/active` * Data: - field | type | Description - ---|---|--- - `password` | string | Optional: Password is only required for users which are self joined or guests and only when the conversation has `hasPassword` set to true. - `force` | bool | If set to `false` and the user has an active session already a `409 Conflict` will be returned (Default: true - to keep the old behaviour) +| field | type | Description | +|------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------| +| `password` | string | Optional: Password is only required for users which are self joined or guests and only when the conversation has `hasPassword` set to true. | +| `force` | bool | If set to `false` and the user has an active session already a `409 Conflict` will be returned (Default: true - to keep the old behaviour) | * Response: - Status code: @@ -121,11 +121,11 @@ - Data in case of `409 Conflict`: - field | type | Description - ---|---|--- - `sessionId` | string | 512 character long string - `inCall` | int | Flags whether the conflicting session is in a potential call - `lastPing` | int | Timestamp of the last ping of the conflicting session +| field | type | Description | +|-------------|--------|--------------------------------------------------------------| +| `sessionId` | string | 512 character long string | +| `inCall` | int | Flags whether the conflicting session is in a potential call | +| `lastPing` | int | Timestamp of the last ping of the conflicting session | ## Resend participant emails @@ -134,9 +134,9 @@ * Endpoint: `/room/{token}/participants/resend-invitations` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int or null | Attendee id can be used for guests and users, not setting it will resend all invitations +| field | type | Description | +|--------------|-------------|------------------------------------------------------------------------------------------| +| `attendeeId` | int or null | Attendee id can be used for guests and users, not setting it will resend all invitations | * Response: - Status code: @@ -160,9 +160,9 @@ * Endpoint: `/room/{token}/moderators` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int | Attendee id can be used for guests and users +| field | type | Description | +|--------------|------|----------------------------------------------| +| `attendeeId` | int | Attendee id can be used for guests and users | * Response: - Status code: @@ -179,9 +179,9 @@ * Endpoint: `/room/{token}/moderators` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int | Attendee id can be used for guests and users +| field | type | Description | +|--------------|------|----------------------------------------------| +| `attendeeId` | int | Attendee id can be used for guests and users | * Response: - Status code: @@ -198,11 +198,11 @@ * Endpoint: `/room/{token}/attendees/permissions` * Data: - field | type | Description - ---|---|--- - `attendeeId` | int | Attendee id can be used for guests and users - `mode` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. - `permissions` | int | New permissions for the attendee, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. +| field | type | Description | +|---------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `attendeeId` | int | Attendee id can be used for guests and users | +| `mode` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. | +| `permissions` | int | New permissions for the attendee, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. | * Response: - Status code: @@ -220,10 +220,10 @@ * Endpoint: `/room/{token}/attendees/permissions/all` * Data: - field | type | Description - ---|---|--- - `mode` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. - `permissions` | int | New permissions for the attendees, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. +| field | type | Description | +|---------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `mode` | string | Mode of how permissions should be manipulated [constants list](constants.md#attendee-permission-modifications). If the permissions were `0` (default) and the modification is `add` or `remove`, they will be initialised with the call or default conversation permissions before, falling back to `126` for moderators and `118` for normal participants. | +| `permissions` | int | New permissions for the attendees, see [constants list](constants.md#attendee-permissions). If permissions are not `0` (default), the `1` (custom) permission will always be added. | * Response: - Status code: @@ -256,9 +256,9 @@ Note: This is only allowed with validate SIP bridge requests * Endpoint: `/guest/{token}/name` * Data: - field | type | Description - ---|---|--- - `displayName` | string | The new display name +| field | type | Description | +|---------------|--------|----------------------| +| `displayName` | string | The new display name | * Response: - Status code: diff --git a/docs/reaction.md b/docs/reaction.md index a4199949f..0185886ff 100644 --- a/docs/reaction.md +++ b/docs/reaction.md @@ -9,9 +9,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 * Endpoint: `/reaction/{token}/{messageId}` * Data: - field | type | Description - ---|---|--- - `reaction` | string | the reaction emoji +| field | type | Description | +|------------|--------|--------------------| +| `reaction` | string | the reaction emoji | * Response: - Status code: @@ -23,12 +23,12 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 - Data: Array with data of reactions: - field | type | Description - ---|---|--- - `actorType` | string | `guests` or `users` - `actorId` | string | Actor id of the reacting participant - `actorDisplayName` | string | Display name of the reaction author - `timestamp` | int | Timestamp in seconds and UTC time zone +| field | type | Description | +|--------------------|--------|----------------------------------------| +| `actorType` | string | `guests` or `users` | +| `actorId` | string | Actor id of the reacting participant | +| `actorDisplayName` | string | Display name of the reaction author | +| `timestamp` | int | Timestamp in seconds and UTC time zone | ## Delete a reaction @@ -37,9 +37,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 * Endpoint: `/reaction/{token}/{messageId}` * Data: - field | type | Description - ---|---|--- - `reaction` | string | the reaction emoji +| field | type | Description | +|------------|--------|--------------------| +| `reaction` | string | the reaction emoji | * Response: - Status code: @@ -50,12 +50,12 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 - Data: Array with data of reactions: - field | type | Description - ---|---|--- - `actorType` | string | `guests` or `users` - `actorId` | string | Actor id of the reacting participant - `actorDisplayName` | string | Display name of the reaction author - `timestamp` | int | Timestamp in seconds and UTC time zone +| field | type | Description | +|--------------------|--------|----------------------------------------| +| `actorType` | string | `guests` or `users` | +| `actorId` | string | Actor id of the reacting participant | +| `actorDisplayName` | string | Display name of the reaction author | +| `timestamp` | int | Timestamp in seconds and UTC time zone | ## Retrieve reactions of a message by type @@ -64,9 +64,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 * Endpoint: `/reaction/{token}/{messageId}` * Data: - field | type | Description - ---|---|--- - `reaction` | string | **Optional:** the reaction emoji +| field | type | Description | +|------------|--------|----------------------------------| +| `reaction` | string | **Optional:** the reaction emoji | * Response: - Status code: @@ -77,9 +77,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 - Data: Array with data of reactions: - field | type | Description - ---|---|--- - `actorType` | string | `guests` or `users` - `actorId` | string | Actor id of the reacting participant - `actorDisplayName` | string | Display name of the reaction author - `timestamp` | int | Timestamp in seconds and UTC time zone +| field | type | Description | +|--------------------|--------|----------------------------------------| +| `actorType` | string | `guests` or `users` | +| `actorId` | string | Actor id of the reacting participant | +| `actorDisplayName` | string | Display name of the reaction author | +| `timestamp` | int | Timestamp in seconds and UTC time zone | diff --git a/docs/settings.md b/docs/settings.md index 1cb6d9b34..5713dafa8 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -8,10 +8,10 @@ * Endpoint: `/settings/user` * Data: - field | type | Description - ---|---|--- - `key` | string | The user config to set - `value` | string/int | The value to set +| field | type | Description | +|---------|------------|------------------------| +| `key` | string | The user config to set | +| `value` | string/int | The value to set | * Response: - Status code: @@ -21,10 +21,10 @@ ## User settings -Key | Capability | Default | Valid values ----|---|---|--- -`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) +| Key | Capability | Default | Valid values | +|-----------------------|-----------------------------------|---------|----------------------------------------------------------------------------------------------------------| +| `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 @@ -35,11 +35,11 @@ Key | Capability | Default | Valid values 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 +| 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 | * Response: - Status code: diff --git a/docs/webinar.md b/docs/webinar.md index 7f303bb84..638f95272 100644 --- a/docs/webinar.md +++ b/docs/webinar.md @@ -20,10 +20,10 @@ Group and public conversations can be used to host webinars. Those online meetin * Endpoint: `/room/{token}/webinar/lobby` * Data: - field | type | Description - ---|---|--- - `state` | int | New state for the conversation - `timer` | int/null | Timestamp when the lobby state is reset to no lobby +| field | type | Description | +|---------|----------|-----------------------------------------------------| +| `state` | int | New state for the conversation | +| `timer` | int/null | Timestamp when the lobby state is reset to no lobby | * Response: - Status code: @@ -42,9 +42,9 @@ Group and public conversations can be used to host webinars. Those online meetin * Endpoint: `/room/{token}/webinar/sip` * Data: - field | type | Description - ---|---|--- - `state` | int | New SIP state for the conversation (0 = disabled, 1 = enabled) +| field | type | Description | +|---------|------|----------------------------------------------------------------| +| `state` | int | New SIP state for the conversation (0 = disabled, 1 = enabled) | * Response: - Status code: |