spreed/docs/settings.md

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
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	'two-lines'	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 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 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 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
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)
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
grid_videos_limit_enforced	string yes or no	no	No		Whether the number of grid videos should be enforced
changelog	string yes or no	yes	No		Whether the changelog conversation is updated with new features on major releases
has_reference_id	string yes or no	no	Yes		Indicator whether the clients can use the reference value to identify their message, will be automatically set to yes when the repair steps are executed
hide_signaling_warning	string yes or no	no	No	🖌️	Flag that allows to suppress the warning that an HPB should be configured
calls_start_without_media	string yes or no	no	Yes		Whether participants start with enabled or disabled audio and video by default
breakout_rooms	string 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 yes or no	yes	Yes		Enable call recording
call_recording_summary	string yes or no	yes	No	🖌️	Whether call recordings should automatically be summarized when a transcription and summary provider is enabled.
call_recording_transcription	string yes or no	no	No		Whether call recordings should automatically be transcribed when a transcription provider is enabled.
sip_dialout	string yes or no	no	Yes		SIP dial-out is allowed when a SIP bridge is configured
federation_enabled	string yes or no	no	Yes		🏗️ Work in progress: Whether or not federation with this instance is allowed
federation_incoming_enabled	string 1 or 0	1	Yes		🏗️ Work in progress: Whether users of this instance can be invited to federated conversations
federation_outgoing_enabled	string 1 or 0	1	Yes		🏗️ Work in progress: Whether users of this instance can invite federated users into conversations
federation_only_trusted_servers	string 1 or 0	0	Yes		🏗️ Work in progress: Whether federation should be limited to the list of "Trusted servers"
conversations_files	string 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 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 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 1 or 0	0	No	🖌️	Whether the Matterbridge integration is enabled and can be configured
force_passwords	string 1 or 0	0	No	️	Whether public chats are forced to use a password
create_samples	string 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 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 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 1 or 0	0	No		Whether guests are allowed to use the virtual backgrounds provided via themes/talk-backgrounds/
backgrounds_default_for_users	string 1 or 0	1	No		Whether users are allowed to use the default virtual backgrounds provided by the releases
backgrounds_upload_users	string 1 or 0	1	No		Whether users are allowed to upload custom virtual backgrounds and choose from their Nextcloud Files
guests_play_sounds	string 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 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 Desktop 1.2.2	-	Make automatic attempts to recover suspended / expired signaling session to allow join the call without page reload