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 OKWhen the value was updated400 Bad RequestWhen the key or value was invalid401 UnauthorizedWhen the user is not logged in
- Status code:
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 |
typing_privacy |
config => chat => typing-privacy |
0 |
One of the typing privacy constants from the constants list |
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 |
'' falling back to app config with the same name |
One of the constants from the constants list |
chat_style |
config => chat => chat-style |
'' falling back to app config with the same name |
One of the constants from the constants list |
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 ForbiddenWhen the user is not an admin
- Status code:
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 |
start_calls_groups |
string[] | [] |
Yes | 🖌️ | List of group ids that are allowed to start calls (everyone when empty). This also applies to moderators; guests and federated users can then never start calls. For federated conversations the host server decides. Others can still chat and join ongoing calls |
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 |
string[] | [] |
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 |
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 |
stringES256, 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 |
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 | 1 |
No | 🖌️ | Default notification level for group conversations constants list (Default changed from 2 (mentions) to 1 (always) in Nextcloud 33 for new installations) |
default_permissions |
int | 246 |
Yes | Default permissions for non-moderators (see constants list for bit flags) | |
recording_consent |
int | 0 |
Yes | 🖌️ | Whether users have to agree on being recorded before they can join the call (see constants) |
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) |
|
retention_classified_rooms |
int | 3600 |
No | Retention period of classified conversations in seconds after a call happened (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 below) | |
experiments_guests |
int | 0 |
Yes | Bit flag of experiments that should be enabled for guests on this server (see Experiments below) | |
summary_threshold |
int | 100 |
No | Amount of unread messages a user needs before they see the option to summarize with AI | |
feature_hints_hidden |
int | 0 |
Yes | 🖌️ | Feature hints that should be hidden. Set to 999999 to hide all. |
certificate_expiration_days |
int | 10 |
No | Minimum days a certificate needs to be valid for, before an expiration notification will be shown. (default 10, minimum 0 and maximum 365) | |
grid_videos_limit_enforced |
bool | false |
No | Whether the number of grid videos should be enforced | |
changelog |
bool | true |
No | Whether the changelog conversation is updated with new features on major releases | |
hide_signaling_warning |
bool | false |
No | 🖌️ | Flag that allows to suppress the warning that an HPB should be configured |
conversations_list_style |
stringtwo-lines or compact |
two-lines |
No | Default conversation list style when not overwritten by the user | |
chat_style |
stringsplit or unified |
split |
No | Default chat style when not overwritten by the user | |
calls_start_without_media |
bool | false |
No | Whether participants start with enabled or disabled audio and video by default | |
breakout_rooms |
bool | true |
Yes | Whether or not breakout rooms are allowed (Will only prevent creating new breakout rooms. Existing conversations are not modified.) | |
call_recording |
stringyes or no |
yes |
Yes | Enable call recording | |
call_recording_summary |
stringyes or no |
yes |
No | 🖌️ | Whether call recordings should automatically be summarized when a transcription and summary provider is enabled. |
call_recording_transcription |
bool | false |
Yes | Whether call recordings should automatically be transcribed when a transcription provider is enabled. | |
sip_dialout |
stringyes or no |
no |
Yes | SIP dial-out is allowed when a SIP bridge is configured | |
federation_enabled |
bool | false |
Yes | 🏗️ Work in progress: Whether or not federation with this instance is allowed | |
federation_incoming_enabled |
string1 or 0 |
1 |
Yes | 🏗️ Work in progress: Whether users of this instance can be invited to federated conversations | |
federation_outgoing_enabled |
string1 or 0 |
1 |
Yes | 🏗️ Work in progress: Whether users of this instance can invite federated users into conversations | |
federation_only_trusted_servers |
string1 or 0 |
0 |
Yes | 🏗️ Work in progress: Whether federation should be limited to the list of "Trusted servers" | |
federation_allowed_groups |
string[] | [] |
Yes | 🖌️ | List of local group ids that are allowed to use federated features |
conversations_files |
bool | true |
No | 🖌️ | Whether the files app integration is enabled allowing to start conversations in the right sidebar |
conversations_files_public_shares |
bool | true |
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 |
bool | false |
No | ️ | Whether one-to-one conversations can be left by either participant or should be deleted when one participant leaves |
enable_matterbridge |
bool | false |
No | 🖌️ | Whether the Matterbridge integration is enabled and can be configured |
force_passwords |
bool | false |
No | ️ | Whether public chats are forced to use a password |
create_samples |
bool | true |
No | ️ | Create sample conversations (the content can be overwritten by providing files in a provided samples_directory app config) |
call_end_to_end_encryption |
bool | false |
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 |
bool | false |
No | Additionally enable the lobby for inactive rooms so they can only be read by moderators. | |
backgrounds_branded_for_guests |
bool | false |
No | Whether guests are allowed to use the virtual backgrounds provided via themes/talk-backgrounds/ |
|
backgrounds_default_for_users |
bool | true |
No | Whether users are allowed to use the default virtual backgrounds provided by the releases | |
backgrounds_upload_users |
bool | true |
No | Whether users are allowed to upload custom virtual backgrounds and choose from their Nextcloud Files | |
guests_play_sounds |
bool | true |
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 | Completed | Web 21.1.0 Desktop 1.2.2-beta |
Web 23.0.0 Desktop 2.x.x |
Instead of refreshing the participant list repeatingly during calls, the data is generated from received signaling messages |
| 2 | Completed | Web 21.1.0 Desktop 1.2.2 |
Web 23.0.0 Desktop 2.x.x |
Make automatic attempts to recover suspended / expired signaling session to allow join the call without page reload |
| 4 | Completed | Web 22.0.3 Desktop 2.0.4 |
Web 23.0.0 Desktop 2.x.x |
Send chat messages via the High performance-backend / websocket |