diff options
Diffstat (limited to 'docs/conversation.md')
-rw-r--r-- | docs/conversation.md | 198 |
1 files changed, 99 insertions, 99 deletions
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** |