# Settings API

* Base endpoint: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 19

## Set user´s settings

* Method: `POST`
* Endpoint: `/settings/user`
* Data:

| field   | type       | Description            |
|---------|------------|------------------------|
| `key`   | string     | The user config to set |
| `value` | string/int | The value to set       |

* Response:
    - Status code:
        + `200 OK` When the value was updated
        + `400 Bad Request` When the key or value was invalid
        + `401 Unauthorized` When the user is not logged in

## User settings

**Note:** Settings from `calls_start_without_media` onwards can not be set via above API.
Instead, the server API `POST /ocs/v2.php/apps/provisioning_api/api/v1/config/users/{appId}/{configKey}` needs to be used.

| Key                         | Capability                                  | Default                                            | Valid values                                                                                             |
|-----------------------------|---------------------------------------------|----------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| `attachment_folder`         | `config => attachments => folder`           | Value of app config `default_attachment_folder`    | 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) |
| `typing_privacy`            | `config => chat => typing-privacy`          | `0`                                                | One of the typing privacy constants from the [constants list](constants.md#participant-typing-privacy)   |
| `play_sounds`               |                                             | `'yes'`                                            | `'yes'` and `'no'`                                                                                       |
| `calls_start_without_media` | `config => call => start-without-media`     | `''` falling back to app config with the same name | `'yes'` and `'no'`                                                                                       |
| `blur_virtual_background`   | `config => call => blur-virtual-background` | `'no'`                                             | `'yes'` and `'no'`                                                                                       |
| `conversations_list_style`  | `config => conversations => list-style`     | `'two-lines'`                                      | One of the constants from the [constants list](constants.md#conversation-list-style)                     |

## Set SIP settings

* Required capability: `sip-support`
* Method: `POST`
* Endpoint: `/settings/sip`
* Data:

    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                            |

* Response:
    - Status code:
        + `403 Forbidden` When the user is not an admin

## App configuration

**Note:** All app configs are stored as `string` in the `oc_appconfig` database table. Arrays and objects are therefor JSON encoded, integers are casted to string and booleans are replaced with `0/1` or `no/yes` strings.

When available the dedicated UI or OCC command option should be used to configure the setting rather than directly manipulating the database.

Legend:

* `Hash` - Whether the changing the config changes the Talk version hash triggering clients to refresh capabilities
* 🖌️ - UI option in the admin settings available
* 💻 - Dedicated OCC command available

| Key                                  | Internal type                                                    | Default    | Hash | Option | Valid values                                                                                                                                                                                                                                                                     |
|--------------------------------------|------------------------------------------------------------------|------------|------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `allowed_groups`                     | string[]                                                         | `[]`       | Yes  | 🖌️    | List of group ids that are allowed to use Talk                                                                                                                                                                                                                                   |
| `sip_bridge_groups`                  | string[]                                                         | `[]`       | Yes  | 🖌️    | List of group ids that are allowed to enable SIP dial-in in a conversation                                                                                                                                                                                                       |
| `start_conversations`                | string[]                                                         | `[]`       | Yes  | 🖌️    | List of group ids that are allowed to create conversations                                                                                                                                                                                                                       |
| `federation_allowed_groups`          | string[]                                                         | `[]`       | Yes  | 🖌️    | 🏗️ *Work in progress:* List of group ids that are allowed to invite federated users into their conversations (everyone when empty)                                                                                                                                              |
| `hosted-signaling-server-account`    | array                                                            | `{}`       | No   | 🖌️    | Account information of the hosted signaling server                                                                                                                                                                                                                               |
| `stun_servers`                       | array[]                                                          | `[]`       | Yes  | 🖌💻️  | List of STUN servers, should be configured via the web interface or the OCC commands                                                                                                                                                                                             |
| `turn_servers`                       | array[]                                                          | `[]`       | Yes  | 🖌️💻  | List of TURN servers, should be configured via the web interface or the OCC commands                                                                                                                                                                                             |
| `recording_servers`                  | array[]                                                          | `[]`       | Yes  | 🖌️    | List of recording servers, should be configured via the web interface                                                                                                                                                                                                            |
| `signaling_servers`                  | array[]                                                          | `[]`       | Yes  | 🖌️💻  | List of signaling servers, should be configured via the web interface or the OCC commands                                                                                                                                                                                        |
| `signaling_mode`                     | string<br>`internal` or `external` or `conversation_cluster`     | `internal` | Yes  |        | `internal` when no HPB is configured, `external` when configured, `conversation_cluster` is an experimental flag that is deprecated                                                                                                                                              |
| `sip_bridge_dialin_info`             | string                                                           |            | Yes  | 🖌️    | Additional information added in the SIP dial-in invitation mail and sidebar                                                                                                                                                                                                      |
| `sip_bridge_dialout_anonymous`       | bool                                                             | false      | No   |        | When set to true, all out-going SIP calls will be anonymous calls (CLIR)                                                                                                                                                                                                         |
| `sip_bridge_dialout_number`          | string                                                           |            | No   |        | Fallback phone number that is used as caller for out-going calls when the user has no phone-number configured (has to be E164 `+49123456789` formatted)                                                                                                                          |
| `sip_bridge_dialout_prefix`          | string                                                           | `+`        | No   |        | Prefix that is added before the first configured phone-number of a user to make it a valid E164 number to be used as a caller for out-going calls                                                                                                                                |
| `sip_bridge_shared_secret`           | string                                                           |            | Yes  | 🖌️    | Shared secret allowing the SIP bridge to authenticate on the Nextcloud server                                                                                                                                                                                                    |
| `signaling_ticket_secret`            | string                                                           |            | Yes  |        | Secret used to secure the signaling tickets for guests (255 character random string)                                                                                                                                                                                             |
| `signaling_token_alg`                | string<br>`ES256`, `ES384`, `RS256`, `RS384`, `RS512` or `EdDSA` | `ES256`    | Yes  |        | Algorithm for the signaling tickets                                                                                                                                                                                                                                              |
| `signaling_token_privkey_*`          | string                                                           | *          | Yes  |        | Private key for the signaling ticket creation by the server                                                                                                                                                                                                                      |
| `signaling_token_pubkey_*`           | string                                                           | *          | Yes  |        | Public key for the signaling ticket creation by the server                                                                                                                                                                                                                       |
| `hosted-signaling-server-nonce`      | string                                                           |            | No   |        | Temporary nonce while configuring the hosted signaling server                                                                                                                                                                                                                    |
| `hosted-signaling-server-account-id` | string                                                           |            | No   |        | Account identifier of the hosted signaling server                                                                                                                                                                                                                                |
| `matterbridge_binary`                | string                                                           |            | No   |        | Path to the matterbridge binary file                                                                                                                                                                                                                                             |
| `bridge_bot_password`                | string                                                           |            | No   |        | Automatically generated password of the matterbridge bot user profile                                                                                                                                                                                                            |
| `default_attachment_folder`          | string                                                           | `/Talk`    | No   |        | Specify default attachment folder location                                                                                                                                                                                                                                       |
| `samples_directory`                  | string                                                           |            | No   |        | Specify a readable directory that contains other sample conversation data                                                                                                                                                                                                        |
| `start_calls`                        | int                                                              | `0`        | Yes  | 🖌️    | Who can start a call, see [constants list](constants.md#start-call)                                                                                                                                                                                                              |
| `max_call_duration`                  | int                                                              | `0`        | No   |        | Maximum duration of a call in seconds, 0 for unlimited. Federated calls will be terminated based on the setting of the host server. Calls are ended via a background job, so system cron should be used and calls will last a bit longer (until the next execution of the cron). |
| `max-gif-size`                       | int                                                              | `3145728`  | No   |        | Maximum file size for clients to render gifs previews with animation                                                                                                                                                                                                             |
| `session-ping-limit`                 | int                                                              | `200`      | No   |        | Number of sessions the HPB can ping in a single request                                                                                                                                                                                                                          |
| `token_entropy`                      | int                                                              | `8`        | No   |        | Length of conversation tokens, can be increased to make tokens harder to guess but reduces readability and dial-in comfort                                                                                                                                                       |
| `default_group_notification`         | int                                                              | `2`        | No   | 🖌️    | Default notification level for group conversations [constants list](constants.md#participant-notification-levels)                                                                                                                                                                |
| `default_permissions`                | int                                                              | `246`      | Yes  |        | Default permissions for non-moderators (see [constants list](constants.md#attendee-permissions) for bit flags)                                                                                                                                                                   |
| `recording_consent`                  | int                                                              | `0`        | Yes  | 🖌️    | Whether users have to agree on being recorded before they can join the call (see [constants](constants.md#recording-consent-required))                                                                                                                                           |
| `grid_videos_limit`                  | int                                                              | `19`       | No   |        | Maximum number of videos to show (additional to the own video)                                                                                                                                                                                                                   |
| `sip_dialin_default`                 | int                                                              | `0`        | No   |        | Default value of SIP dial-in when creating new conversations                                                                                                                                                                                                                     |
| `retention_event_rooms`              | int                                                              | `28`       | No   |        | Retention period of event conversations in days (`0` means no-retention)                                                                                                                                                                                                         |
| `retention_phone_rooms`              | int                                                              | `7`        | No   |        | Retention period of phone dial-in and dial-out conversations in days (`0` means no-retention)                                                                                                                                                                                    |
| `retention_instant_meetings`         | int                                                              | `1`        | No   |        | Retention period of instant meetings in days (`0` means no-retention)                                                                                                                                                                                                            |
| `experiments_users`                  | int                                                              | `0`        | Yes  |        | Bit flag of experiments that should be enabled for logged-in users on this server (see [Experiments](#experiments) below)                                                                                                                                                        |
| `experiments_guests`                 | int                                                              | `0`        | Yes  |        | Bit flag of experiments that should be enabled for guests on this server (see [Experiments](#experiments) below)                                                                                                                                                                 |
| `summary_threshold`                  | int                                                              | `100`      | No   |        | Amount of unread messages a user needs before they see the option to summarize with AI                                                                                                                                                                                           |
| `grid_videos_limit_enforced`         | string<br>`yes` or `no`                                          | `no`       | No   |        | Whether the number of grid videos should be enforced                                                                                                                                                                                                                             |
| `changelog`                          | string<br>`yes` or `no`                                          | `yes`      | No   |        | Whether the changelog conversation is updated with new features on major releases                                                                                                                                                                                                |
| `hide_signaling_warning`             | string<br>`yes` or `no`                                          | `no`       | No   | 🖌️    | Flag that allows to suppress the warning that an HPB should be configured                                                                                                                                                                                                        |
| `calls_start_without_media`          | string<br>`yes` or `no`                                          | `no`       | Yes  |        | Whether participants start with enabled or disabled audio and video by default                                                                                                                                                                                                   |
| `breakout_rooms`                     | string<br>`yes` or `no`                                          | `yes`      | Yes  |        | Whether or not breakout rooms are allowed (Will only prevent creating new breakout rooms. Existing conversations are not modified.)                                                                                                                                              |
| `call_recording`                     | string<br>`yes` or `no`                                          | `yes`      | Yes  |        | Enable call recording                                                                                                                                                                                                                                                            |
| `call_recording_summary`             | string<br>`yes` or `no`                                          | `yes`      | No   | 🖌️    | Whether call recordings should automatically be summarized when a transcription and summary provider is enabled.                                                                                                                                                                 |
| `call_recording_transcription`       | string<br>`yes` or `no`                                          | `no`       | No   |        | Whether call recordings should automatically be transcribed when a transcription provider is enabled.                                                                                                                                                                            |
| `sip_dialout`                        | string<br>`yes` or `no`                                          | `no`       | Yes  |        | SIP dial-out is allowed when a SIP bridge is configured                                                                                                                                                                                                                          |
| `federation_enabled`                 | string<br>`yes` or `no`                                          | `no`       | Yes  |        | 🏗️ *Work in progress:* Whether or not federation with this instance is allowed                                                                                                                                                                                                  |
| `federation_incoming_enabled`        | string<br>`1` or `0`                                             | `1`        | Yes  |        | 🏗️ *Work in progress:* Whether users of this instance can be invited to federated conversations                                                                                                                                                                                 |
| `federation_outgoing_enabled`        | string<br>`1` or `0`                                             | `1`        | Yes  |        | 🏗️ *Work in progress:* Whether users of this instance can invite federated users into conversations                                                                                                                                                                             |
| `federation_only_trusted_servers`    | string<br>`1` or `0`                                             | `0`        | Yes  |        | 🏗️ *Work in progress:* Whether federation should be limited to the list of "Trusted servers"                                                                                                                                                                                    |
| `conversations_files`                | string<br>`1` or `0`                                             | `1`        | No   | 🖌️    | Whether the files app integration is enabled allowing to start conversations in the right sidebar                                                                                                                                                                                |
| `conversations_files_public_shares`  | string<br>`1` or `0`                                             | `1`        | No   | 🖌️    | Whether the public share integration is enabled allowing to start conversations in the right sidebar on the public share page (Requires `conversations_files` also to be enabled)                                                                                                |
| `delete_one_to_one_conversations`    | string<br>`1` or `0`                                             | `0`        | No   | ️      | Whether one-to-one conversations can be left by either participant or should be deleted when one participant leaves                                                                                                                                                              |
| `enable_matterbridge`                | string<br>`1` or `0`                                             | `0`        | No   | 🖌️    | Whether the Matterbridge integration is enabled and can be configured                                                                                                                                                                                                            |
| `force_passwords`                    | string<br>`1` or `0`                                             | `0`        | No   | ️      | Whether public chats are forced to use a password                                                                                                                                                                                                                                |
| `create_samples`                     | string<br>`1` or `0`                                             | `1`        | No   | ️      | Create sample conversations (the content can be overwritten by providing files in a provided `samples_directory` app config)                                                                                                                                                     |
| `call_end_to_end_encryption`         | string<br>`1` or `0`                                             | `0`        | No   | 🖌️    | Whether clients should end-to-end encrypt streams in calls (Only supported with High-performance backend)                                                                                                                                                                        |
| `inactivity_lock_after_days`         | int                                                              | `0`        | No   |        | A duration (in days) after which rooms are locked. Calculated from the last activity in the room.                                                                                                                                                                                |
| `inactivity_enable_lobby`            | string<br>`1` or `0`                                             | `0`        | No   |        | Additionally enable the lobby for inactive rooms so they can only be read by moderators.                                                                                                                                                                                         |
| `backgrounds_branded_for_guests`     | string<br>`1` or `0`                                             | `0`        | No   |        | Whether guests are allowed to use the virtual backgrounds provided via `themes/talk-backgrounds/`                                                                                                                                                                                |
| `backgrounds_default_for_users`      | string<br>`1` or `0`                                             | `1`        | No   |        | Whether users are allowed to use the default virtual backgrounds provided by the releases                                                                                                                                                                                        |
| `backgrounds_upload_users`           | string<br>`1` or `0`                                             | `1`        | No   |        | Whether users are allowed to upload custom virtual backgrounds and choose from their Nextcloud Files                                                                                                                                                                             |
| `guests_play_sounds`                 | string<br>`1` or `0`                                             | `1`        | No   |        | Whether guests hear the join and leave sounds by default                                                                                                                                                                                                                         |

## Experiments

Features that can be toggled on-off with the `experiments_users` and `experiments_guests` bit flags:

| Bit | Status | Introduced                       | Ended | Description                                                                                                                 |
|-----|--------|----------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|
| 1   | Active | Web 21.1.0<br>Desktop 1.2.2-beta | -     | Instead of refreshing the participant list repeatingly during calls, the data is generated from received signaling messages |
| 2   | Active | Web 21.1.0<br>Desktop 1.2.2      | -     | Make automatic attempts to recover suspended / expired signaling session to allow join the call without page reload         |
| 4   | Active | Web 22.0.3<br>Desktop 2.0.4      | -     | Send chat messages via the High performance-backend / websocket                                                             |
