User settings

These routes change your account-wide user settings and the notification settings for each guild and for DMs. Only user tokens can call them, and bot and OAuth2 tokens get 403 ACCESS_DENIED.

Presence status values

Value	Description
online	Shown as online
dnd	Shown as do not disturb
idle	Shown as idle
invisible	Shown as offline to everyone else while the account stays connected

Theme values

Value	Description
dark	Dark theme
dark_legacy	Previous dark theme
coal	Coal theme
light	Light theme
system	Follows the operating system

Notification levels

Value	Name	Description
0	ALL_MESSAGES	Notify for every message
1	ONLY_MENTIONS	Notify only for mentions
2	NO_MESSAGES	Do not notify for messages
3	INHERIT	Use the parent setting

Guild mute configuration object

Mute expiry for a guild, for DMs, for a channel override or for a thread member.

Structure

Field	Type	Description
end_time	?ISO8601 timestamp	When the mute stops, or null for no expiry
selected_time_window	integer	The mute duration the client selected, or 0

Guild mute configuration input object

The input form of the guild mute configuration object.

Structure

Field	Type	Description
end_time?1	?ISO8601 timestamp | integer	When the mute stops, or null for no expiry
selected_time_window	integer	The mute duration the client selected

¹ An ISO 8601 string or Unix milliseconds

Channel notification override object

Notification settings for one channel.

Structure

Field	Type	Description
collapsed	boolean	Whether the channel category is collapsed
message_notifications	integer	Notification level
muted	boolean	Whether the channel is muted
mute_config	?guild mute configuration object	The mute configuration, or null when none is stored
unread_badges	?integer	Notification level for unread badges, or null to inherit
flags?1	integer	New post notification flags, NEW_FORUM_THREADS_OFF (1 << 13) and NEW_FORUM_THREADS_ON (1 << 14)

¹ Only in guild settings, when the value is not zero and the session declares the channel_threads client capability

Channel notification override input object

The input form of the channel notification override object.

Structure

Field	Type	Description
collapsed	boolean	Whether the channel category is collapsed
message_notifications	integer	Notification level
muted	boolean	Whether the channel is muted
mute_config?	?guild mute configuration input object	The mute configuration, or null to clear it
unread_badges?	?integer	Notification level for unread badges, or null to inherit
flags?1	integer	New post notification flags

¹ Fluxer keeps only NEW_FORUM_THREADS_OFF and NEW_FORUM_THREADS_ON. It ignores flags in DM settings and when the session doesn't declare channel_threads. An omitted or ignored flags keeps the stored value

User guild settings object

Notification settings for one guild, or for all DMs when guild_id is null.

Structure

Field	Type	Description
guild_id	?snowflake	The ID of the guild, or null for DM settings
message_notifications	integer	The default notification level
muted	boolean	Whether the guild or DMs are muted
mute_config	?guild mute configuration object	The mute configuration, or null when none is stored
mobile_push	boolean	Whether push notifications are enabled
suppress_everyone	boolean	Whether @everyone mentions are suppressed
suppress_roles	boolean	Whether role mentions are suppressed
hide_muted_channels	boolean	Whether muted channels are hidden
channel_overrides1	?map[snowflake, channel notification override object]	The per-channel overrides, or null when none are set
unread_badges	?integer	The default notification level for unread badges, or null to follow message_notifications
version2	integer	The revision of this settings object

¹ Without channel_threads, a session gets no override for a forum or media channel

² Increases on every write. Ignore a User Guild Settings Update whose version is lower than the one you have

suppress_everyone and suppress_roles apply only in guilds, and a suppressed mention doesn't add to mention_count or recent mentions.

Example

{
  "guild_id": null,
  "message_notifications": 1,
  "muted": false,
  "mute_config": null,
  "mobile_push": true,
  "suppress_everyone": false,
  "suppress_roles": false,
  "hide_muted_channels": false,
  "channel_overrides": null,
  "unread_badges": null,
  "version": 4
}

Guild settings update fields

Both notification settings routes accept these fields. An omitted field keeps its stored value.

Structure

Field	Type	Description
message_notifications?	integer	The default notification level, default INHERIT
muted?	boolean	Whether the guild is muted, default false
mute_config?	?guild mute configuration input object	The mute configuration, or null to clear it
mobile_push?	boolean	Whether push notifications are enabled, default true
suppress_everyone?	boolean	Whether @everyone mentions are suppressed, default false
suppress_roles?	boolean	Whether role mentions are suppressed, default false
hide_muted_channels?	boolean	Whether muted channels are hidden, default false
channel_overrides?1	?map[snowflake, channel notification override input object]	The complete per-channel override map, or null to clear it
unread_badges?	?integer	The default notification level for unread badges, or null to follow message_notifications

¹ The map replaces every override, and an empty map clears them. Without channel_threads, the stored overrides of forum and media channels stay

User settings update object

The input form of the user settings object. An omitted field keeps its stored value, and a field you send replaces the stored value in full.

Structure

Field	Type	Description
status?	string	Presence status, not offline
status_resets_at?1	?ISO8601 timestamp | integer	The time your client should switch status to status_resets_to, or null to clear it
status_resets_to?	?string	Presence status to set at status_resets_at, not offline, or null to clear it
theme?	string	Theme value
locale?2	string	Interface locale
restricted_guilds?3	array[snowflake]	The guilds where member direct messages are restricted (max 200)
bot_restricted_guilds?3	array[snowflake]	The guilds where bot direct messages are restricted (max 200)
default_guilds_restricted?	boolean	Whether new guilds restrict member direct messages
bot_default_guilds_restricted?	boolean	Whether new guilds restrict bot direct messages
inline_attachment_media?	boolean	Whether attachment media is shown inline
inline_embed_media?	boolean	Whether embed media is shown inline
gif_auto_play?	boolean	Whether GIFs play automatically
render_embeds?	boolean	Whether message embeds are shown
render_reactions?	boolean	Whether message reactions are shown
animate_emoji?	boolean	Whether custom emoji animate
animate_stickers?	integer	Sticker animation setting
render_spoilers?	integer	Spoiler rendering setting
message_display_compact?	boolean	Whether messages use compact display
flags?4	integer	Friend source flags
friend_source_flags?4	integer	Friend source flags
incoming_call_flags?5	integer	Incoming call flags
group_dm_add_permission_flags?5	integer	Group DM add permission flags
guild_folders?	array[guild folder input object]	The complete guild folder layout (max 100)
custom_status?	?custom status input object	The custom status, or null to clear it
afk_timeout?	integer	Idle seconds before the account is shown as away (60-600)
time_format?	integer	Time format setting
developer_mode?	boolean	Whether developer mode is on
trusted_domains?6	array[string]	The trusted external link domains (max 1000, each 1-253 characters)
default_hide_muted_channels?	boolean	Whether new guilds hide muted channels
sensitive_content_friend_dm_filter?7	integer	Sensitive media filter for friend direct messages
sensitive_content_non_friend_dm_filter?7	integer	Sensitive media filter for non-friend direct messages
sensitive_content_guild_filter?8	integer	Guild sensitive media filter
suppress_unprivileged_self_mentions?9	boolean	Whether direct and reply mentions from unprivileged users are suppressed
suppress_unprivileged_self_mentions_bypass_user_ids?9	?array[snowflake]	The users exempt from mention suppression
staff_dm_access_user_ids?9	?array[snowflake]	The users granted staff direct message access
profile_privacy?	integer	Profile privacy level
privacy_setup_version?	integer	The privacy setup version the user reviewed (1-1000), which also sets privacy_setup_completed_at to now
synced_preferences?10	?string	The base64 fluxer.user.preferences.v1.SyncedPreferences snapshot, or null to clear it
synced_preferences_base_hash?11	string	The lowercase hex SHA-256 of the decoded bytes of the stored snapshot the new one was built on
guild_positions?	array[snowflake]	Accepted and ignored (max 200)
default_share_voice_activity?	boolean	Accepted and ignored

¹ An ISO 8601 string or Unix milliseconds. Anything else fails with the field code INVALID_ISO_TIMESTAMP

² Must match a supported locale exactly. It also sets the language of emails Fluxer sends you

³ Duplicates are removed

⁴ flags is a legacy alias for friend_source_flags, which wins when both are sent

⁵ When the value has FRIENDS_ONLY, Fluxer keeps only that flag. Otherwise, when it has NOBODY, Fluxer keeps only NOBODY. incoming_call_flags also keeps SILENT_EVERYONE

⁶ The single entry * trusts every domain. Combining it with another entry fails with the field code INVALID_TRUSTED_DOMAINS

⁷ An account that isn't a verified adult can set only blur or block, and any other value fails with the field code AGE_RESTRICTED

⁸ An account that isn't a verified adult can't change this field, and it fails with the field code AGE_RESTRICTED

⁹ Only staff accounts can set these fields

¹⁰ At most 524288 bytes once decoded. A value that is too large fails with the field code TOO_LARGE, and one that doesn't decode fails with INVALID_FORMAT

¹¹ Fluxer checks the hash only when synced_preferences is also sent. It hashes the stored snapshot exactly as the settings object returns it, and an empty snapshot hashes as zero bytes. When the hashes differ, Fluxer writes nothing and returns 409 SYNCED_PREFERENCES_CONFLICT. Without this field, the new snapshot replaces the stored one unchecked

Guild folder input object

One folder of a submitted guild folder layout.

Structure

Field	Type	Description
id1	integer	The ID of the folder
name?	?string	The name of the folder (0-100 characters)
color?2	?integer	The packed 24-bit RGB color (0-16777215), default 0
flags?	integer	Guild folder flags, default 0
icon?	string	Guild folder icon, default folder
guild_ids	array[snowflake]	The guild IDs in display order (max 200)

¹ At least -1, which is the uncategorized folder

² Out-of-range values fail with COLOR_VALUE_TOO_LOW or COLOR_VALUE_TOO_HIGH

Fluxer adds an empty uncategorized folder when your layout has none. A guild ID in more than one folder stays in only one of them. A folder with a name wins over one without, then any folder wins over the uncategorized folder, then the earlier folder wins.

Send back guild IDs you don't show

The array replaces the stored layout, including guild IDs your client can't resolve. Send those IDs back too, or the update deletes them from the layout.

Joining a guild adds it to the uncategorized folder. Leaving a guild removes it from every folder and deletes every folder left empty except the uncategorized folder. Both send User Settings Update.

Custom status input object

A custom status in a settings update.

Structure

Field	Type	Description
text?1	?string	The status text (1-128 characters)
expires_at?2	?ISO8601 timestamp | integer	The expiry as a timestamp string or Unix milliseconds, or null for no expiry
emoji_id?3	?snowflake	The custom emoji to show
emoji_name?3	?string	The Unicode emoji to show (1-32 characters)

¹ Blocked text or links fail with 403 CONTENT_BLOCKED

² Must be in the future

³ emoji_name is ignored when emoji_id is set. An unknown emoji_id fails with CUSTOM_EMOJI_NOT_FOUND. Fluxer drops the emoji for an account whose feature_global_expressions limit is 0

Settings can keep a custom status after it expires. Hide it once expires_at is in the past.

Initial settings

A new account starts with these settings.

Setting	Initial value
Theme	The theme chosen at registration, or dark
Status	online
Rendering	Everything shown and animated, spoilers hidden until clicked
Incoming calls and group DM additions	Friends only
Guild DM restrictions	None for members and bots
Guild folders	One empty uncategorized folder
AFK timeout	600 seconds
Time format	Automatic
Profile privacy	Visible to all guild members
Voice activity sharing	On
Friend sources	Mutual friends and mutual guilds, and anyone for a verified adult
Sensitive media filters	Friend DMs show for a verified adult and blur otherwise, non-friend DMs block, guilds blur

Get current user settings

GET/v1/users/@me/settings

Returns the user settings object.

Response

Status	Body	Condition
200	user settings object	Settings were returned
404	error response	UNKNOWN_USER when the account has no settings record

The rate limit is 40 requests per 10 seconds, on the user:settings:get bucket.

Modify current user settings

PATCH/v1/users/@me/settings

Modifies the account-wide settings and returns the full user settings object. Sends User Settings Update, and also User Update when the locale changes.

The status you set applies to every session of the account.

JSON body

The body uses the user settings update object.

Response

Status	Body	Condition
200	user settings object	Settings were applied
400	error response	INVALID_FORM_BODY or VALIDATION_ERROR when a field is invalid, with the field code from the footnotes
403	error response	CONTENT_BLOCKED for blocked status text
403	error response	ACCOUNT_LIMITED when a limited account sets a custom status
404	error response	UNKNOWN_USER when the account has no settings record
409	error response	SYNCED_PREFERENCES_CONFLICT when synced_preferences_base_hash doesn't match the stored snapshot

The rate limit is 20 requests per 10 seconds, on the user:settings:update bucket.

Modify voice activity sharing

PUT/v1/users/@me/settings/voice-activity-sharing

Sets the default for sharing voice activity, applies it to your side of every friendship and returns your user object. Sends Relationship Update and User Update. When the default changes, it also sends User Settings Update.

You can change this once every 24 hours, even to the same value. last_voice_activity_sharing_change_at on the user object has the time of the last change.

JSON body

Field	Type	Description
share_voice_activity	boolean	Whether voice activity is shared

Response

Status	Body	Condition
200	user object	The new sharing state was applied
400	error response	INVALID_FORM_BODY with VOICE_ACTIVITY_SHARING_ON_COOLDOWN and retry_after on share_voice_activity during the cooldown
404	error response	UNKNOWN_USER when the account has no settings record

The rate limit is 20 requests per 10 seconds, on the user:settings:update bucket.

Modify DM notification settings

PATCH/v1/users/@me/guilds/@me/settings

Modifies and returns the user guild settings for direct messages and group DMs, with guild_id null. Sends User Guild Settings Update to your own sessions.

JSON body

The body uses the guild settings update fields.

Response

Status	Body	Condition
200	user guild settings object	The settings were applied

The rate limit is 30 requests per 10 seconds, on the user:guild_settings:update bucket.

Modify guild notification settings

PATCH/v1/users/@me/guilds/{guild_id}/settings

Modifies and returns the user guild settings for a guild. Sends User Guild Settings Update to your own sessions.

JSON body

The body uses the guild settings update fields.

Response

Status	Body	Condition
200	user guild settings object	The settings were applied

The rate limit is 30 requests per 10 seconds, on the user:guild_settings:update bucket.