# SingleRoomsByToken Get a room - Catalog: `Spreed` - Schema: `Spreed` This is a read-only table function. The Nextcloud API may not support changing the data or the Invantive UniversalSQL driver for Nextcloud does not cover it. In the latter case, please use the table NativePlatformScalarRequests to upload data to the Nextcloud API. ## Parameters of Table Function The following parameters can be used to control the behaviour of the table function `SingleRoomsByToken`. A value must be provided at all times for required parameters, but optional parameters in general do not need to have a value and the execution will default to a pre-defined behaviour. Values can be specified by position and by name. In both cases, all parameters not specified will be evaluated using their default values. Value specification by position is done by listing all values from the first to the last needed value. For example: a `select * from table(value1, value2, value3)` on a table with four parameters will use the default value for the fourth parameter and the specified values for the first three. Value specification by name is done by listing all values that require a value. For example with `select * from table(name1 => value1, name3 => value3)` on the same table will use the default values for the second and fourth parameters and the specified values for the first and third. | Name | Data Type | Required | Default Value | Documentation | |---|:---:|:---:|:---:|---| | `apiVersion` | `` | ☐ | v4 | Values: v4. | | `talk-sipbridge-checksum` | `` | ☐ | | SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge | | `talk-sipbridge-random` | `` | ☐ | | Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum | | `token` | `` | ☑ | | Token of the room | | `x-nextcloud-federation` | `` | ☐ | | Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request | ## Columns of Table Function The columns of the table function `SingleRoomsByToken` are shown below. Each column has an SQL data type. | Name | Data Type | Label | Required | Documentation | |---|:---:|---|:---:|---| | `ocs_data_actorId` | `varchar2` | | ☐ | The unique identifier for the given actor type | | `ocs_data_actorType` | `varchar2` | | ☐ | Actor type of the current user (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#attendee-types)) | | `ocs_data_attendeeId` | `int64` | | ☐ | Unique attendee id | | `ocs_data_attendeePermissions` | `int64` | | ☐ | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#attendee-permissions)) | | `ocs_data_attendeePin` | `varchar2` | | ☐ | Unique dial-in authentication code for this user, when the conversation has SIP enabled (see `sipEnabled` attribute) | | `ocs_data_avatarVersion` | `varchar2` | | ☐ | Version of conversation avatar used to easier expiration of the avatar in case a moderator updates it, since the avatar endpoint should be cached for 24 hours. (only available with `avatar` capability) | | `ocs_data_breakoutRoomMode` | `int64` | | ☐ | Breakout room configuration mode (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#breakout-room-modes)) (only available with `breakout-rooms-v1` capability) | | `ocs_data_breakoutRoomStatus` | `int64` | | ☐ | Breakout room status (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#breakout-room-status)) (only available with `breakout-rooms-v1` capability) | | `ocs_data_callFlag` | `int64` | | ☐ | Combined flag of all participants in the current call (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#participant-in-call-flag), only available with `conversation-call-flags` capability) | | `ocs_data_callPermissions` | `int64` | | ☐ | 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](https://nextcloud-talk.readthedocs.io/en/latest/constants#attendee-permissions)) | | `ocs_data_callRecording` | `int64` | | ☐ | Type of call recording (see [Constants - Call recording status](https://nextcloud-talk.readthedocs.io/en/latest/constants#call-recording-status)) (only available with `recording-v1` capability) | | `ocs_data_callStartTime` | `int64` | | ☐ | Timestamp when the call was started (only available with `recording-v1` capability) | | `ocs_data_canDeleteConversation` | `char` | | ☐ | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations) | | `ocs_data_canEnableSIP` | `char` | | ☐ | 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 | | `ocs_data_canLeaveConversation` | `char` | | ☐ | Flag if the user can leave the conversation (not possible for the last user with moderator permissions) | | `ocs_data_canStartCall` | `char` | | ☐ | Flag if the user can start a new call in this conversation (joining is always possible) (only available with `start-call-flag` capability) | | `ocs_data_defaultPermissions` | `int64` | | ☐ | Default permissions for new participants (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#attendee-permissions)) | | `ocs_data_description` | `varchar2` | | ☐ | Description of the conversation (can also be empty) (only available with `room-description` capability) | | `ocs_data_displayName` | `varchar2` | | ☐ | `name` if non-empty, otherwise it falls back to a list of participants | | `ocs_data_hasCall` | `char` | | ☐ | Flag if the conversation has an active call | | `ocs_data_hasPassword` | `char` | | ☐ | Flag if the conversation has a password | | `ocs_data_hasScheduledMessages` | `int64` | | ☐ | Required capability: `scheduled-messages` (local) | | `ocs_data_hiddenPinnedId` | `int64` | | ☐ | Required capability: `pinned-messages` | | `ocs_data_id` | `int64` | | ☐ | Numeric identifier of the conversation | | `ocs_data_invitedActorId` | `varchar2` | | ☐ | The cloud id of the invited user | | `ocs_data_isArchived` | `char` | | ☐ | Flag if the conversation is archived by the user (only available with `archived-conversations-v2` capability) | | `ocs_data_isCustomAvatar` | `char` | | ☐ | Flag if the conversation has a custom avatar (only available with `avatar` capability) | | `ocs_data_isFavorite` | `char` | | ☐ | Flag if the conversation is favorited by the user | | `ocs_data_isImportant` | `char` | | ☐ | Required capability: `important-conversations` | | `ocs_data_isSensitive` | `char` | | ☐ | Required capability: `sensitive-conversations` | | `ocs_data_lastActivity` | `int64` | | ☐ | Timestamp of the last activity in the conversation, in seconds and UTC time zone | | `ocs_data_lastCommonReadMessage` | `int64` | | ☐ | 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) | | `ocs_data_lastPing` | `int64` | | ☐ | Timestamp of the user's session making the request | | `ocs_data_lastPinnedId` | `int64` | | ☐ | Required capability: `pinned-messages` | | `ocs_data_lastReadMessage` | `int64` | | ☐ | ID of the last read message in a room (only available with `chat-read-marker` capability) | | `ocs_data_listable` | `int64` | | ☐ | Listable scope for the room (only available with `listable-rooms` capability) | | `ocs_data_liveTranscriptionLanguageId` | `varchar2` | | ☐ | ID of the language to use for live transcriptions in the room, | | `ocs_data_lobbyState` | `int64` | | ☐ | 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](https://nextcloud-talk.readthedocs.io/en/latest/constants#webinar-lobby-states)) | | `ocs_data_lobbyTimer` | `int64` | | ☐ | Timestamp when the lobby will be automatically disabled (only available with `webinary-lobby` capability) | | `ocs_data_mentionPermissions` | `int64` | | ☐ | Whether all participants can mention using `@all` or only moderators (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#mention-permissions)) (only available with `mention-permissions` capability) | | `ocs_data_messageExpiration` | `int64` | | ☐ | The message expiration time in seconds in this chat. Zero if disabled. (only available with `message-expiration` capability) | | `ocs_data_name` | `varchar2` | | ☐ | Name of the conversation (can also be empty) | | `ocs_data_notificationCalls` | `int64` | | ☐ | | | `ocs_data_notificationLevel` | `int64` | | ☐ | The notification level for the user (See [Participant notification levels](https://nextcloud-talk.readthedocs.io/en/latest/constants#participant-notification-levels)) | | `ocs_data_objectId` | `varchar2` | | ☐ | See [Object types](https://nextcloud-talk.readthedocs.io/en/latest/constants#object-types) documentation for explanation | | `ocs_data_objectType` | `varchar2` | | ☐ | The type of object that the conversation is associated with (See [Object types](https://nextcloud-talk.readthedocs.io/en/latest/constants#object-types)) | | `ocs_data_participantFlags` | `int64` | | ☐ | "In call" flags of the user's session making the request (only available with `in-call-flags` capability) | | `ocs_data_participantType` | `int64` | | ☐ | Permissions level of the current user | | `ocs_data_permissions` | `int64` | | ☐ | 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](https://nextcloud-talk.readthedocs.io/en/latest/constants#attendee-permissions)) | | `ocs_data_readOnly` | `int64` | | ☐ | Read-only state for the current user (only available with `read-only-rooms` capability) | | `ocs_data_recordingConsent` | `int64` | | ☐ | Whether recording consent is required before joining a call (Only 0 and 1 will be returned, see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#recording-consent-required)) (only available with `recording-consent` capability) | | `ocs_data_remoteServer` | `varchar2` | | ☐ | | | `ocs_data_remoteToken` | `varchar2` | | ☐ | | | `ocs_data_sessionId` | `varchar2` | | ☐ | `'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](https://nextcloud-talk.readthedocs.io/en/latest/participant/#get-list-of-participants-in-a-conversation) | | `ocs_data_sipEnabled` | `int64` | | ☐ | SIP enable status (see [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants#sip-states)) | | `ocs_data_statusClearAt` | `int64` | | ☐ | Optional: Only available for one-to-one conversations, when `includeStatus=true` is set and the user has a status, can still be null even with a status | | `ocs_data_statusIcon` | `varchar2` | | ☐ | Optional: Only available for one-to-one conversations, when `includeStatus=true` is set and the user has a status, can still be null even with a status | | `ocs_data_statusMessage` | `varchar2` | | ☐ | Optional: Only available for one-to-one conversations, when `includeStatus=true` is set and the user has a status, can still be null even with a status | | `ocs_data_status` | `varchar2` | | ☐ | Optional: Only available for one-to-one conversations, when `includeStatus=true` is set and the user has a status | | `ocs_data_token` | `varchar2` | | ☐ | Token identifier of the conversation which is used for further interaction | | `ocs_data_type` | `int64` | | ☐ | See list of conversation types in the [constants list](https://nextcloud-talk.readthedocs.io/en/latest/constants/#conversation-types) | | `ocs_data_unreadMentionDirect` | `char` | | ☐ | Flag if the user was mentioned directly (ignoring `@all` mentions) since their last visit (only available with `direct-mention-flag` capability) | | `ocs_data_unreadMention` | `char` | | ☐ | Flag if the user was mentioned since their last visit | | `ocs_data_unreadMessages` | `int64` | | ☐ | Number of unread chat messages in the conversation (only available with `chat-v2` capability) | | `ocs_meta_itemsperpage` | `varchar2` | | ☐ | | | `ocs_meta_message` | `varchar2` | | ☐ | | | `ocs_meta_status` | `varchar2` | | ☐ | | | `ocs_meta_statuscode` | `int64` | | ☐ | | | `ocs_meta_totalitems` | `varchar2` | | ☐ | |