User Settings

User settings are options that a user can configure to change the behavior of their account or client. User guild settings are used to control notifications and other customization options on a per-guild basis.

User Settings Proto Object

This object is actually a serialized protobuf message. The individual fields are not yet documented, but the .proto files are available on this repository.

User Settings Proto Type

Value	Name	Description
1	PRELOADED	General Discord user settings
2	FRECENCY	Frecency and favorites storage
3	TEST_SETTINGS	Unknown

Legacy User Settings Object

Contains general user settings. This is deprecated in favour of protobuf user settings.

Legacy User Settings Structure

Field	Type	Description
activity_joining_restricted_guild_ids	array[snowflake]	The IDs of guilds that will not be able to join your current activity
activity_restricted_guild_ids	array[snowflake]	The IDs of guilds your activity presence will be hidden in
afk_timeout	integer	Duration (in seconds) the user needs to be inactive until clients update their AFK state
allow_accessibility_detection	boolean	Whether to allow Discord to track screen reader usage
allow_activity_party_privacy_friends	boolean	Whether to allow friends to join your activity without sending a request
allow_activity_party_privacy_voice_channel ¹	boolean	Whether to allow people in the same voice channel as you to join your activity without sending a request
animate_emoji	boolean	Whether to play animated emojis in chat
animate_stickers	integer	When to animate stickers in chat
contact_sync_enabled	boolean	Whether to enable contact sync on Discord mobile
convert_emoticons	boolean	Whether to convert emoticons into emojis (`:)` -> `🙂`)
custom_status	?custom status object	The custom status of the user, used to sync presence across clients
default_guilds_restricted	boolean	Whether to automatically disable DMs between you and members of new guilds you join
detect_platform_accounts	boolean	Whether to automatically detect accounts from services like Steam and Blizzard when opening the Discord client
developer_mode	boolean	Whether to enable developer mode in-client
disable_games_tab	boolean	Whether to disable the showing of the Games tab
enable_tts_command	boolean	Whether to allow TTS messages to be played/sent
explicit_content_filter	integer	The explicit content filter for explicit content in all messages
friend_discovery_flags	integer	The friend discovery flags
friend_source_flags	?friend source flags object	The friend source flags (default all false)
gif_auto_play	boolean	Whether GIFs are automatically played when Discord client is in focus
guild_folders	array[guild folder object]	The guild folders
inline_attachment_media	boolean	Whether to display attachments when they are uploaded in chat
inline_embed_media	boolean	Whether to display videos and images from links posted in chat
locale	string	The language option chosen by the user
message_display_compact	boolean	Whether to use the compact Discord display mode
native_phone_integration_enabled	boolean	Whether to enable the new Discord mobile phone number friend requesting feature
passwordless (deprecated)	boolean	Whether to enable passwordless login
render_embeds	boolean	Whether to render message embeds
render_reactions	boolean	Whether to render message reactions
restricted_guilds	array[snowflake]	The IDs of guilds that you will not receive DMs from
show_current_game	boolean	Whether to display the currently active game in user presence
status	string	The status of the user, used to sync presence across clients
stream_notifications_enabled	boolean	Whether to receive stream notifications for friends
theme	string	The theme
timezone_offset	integer	The timezone offset from UTC to use (in minutes)
view_nsfw_commands	boolean	Whether NSFW application commands are shown in DMs
view_nsfw_guilds	boolean	Whether NSFW guilds are shown on iOS

¹ Does not apply to community guilds.

Sticker Animation Option

Value	Name	Description
0	ALWAYS_ANIMATE	Always animate stickers
1	ANIMATE_ON_INTERACTION	Animate sticker on interaction
2	NEVER_ANIMATE	Never animate stickers

Legacy Custom Status Structure

Field	Type	Description
text	?string	The custom status text (max 128)
emoji_id ¹	?snowflake	The ID of a guild's custom emoji
emoji_name ¹	?string	The unicode character of the emoji
expires_at	?ISO8601 timestamp	When the custom status will expire

¹ At most one of emoji_id and emoji_name may be set to a non-null value.

Legacy Client Theme

The client theme denotes the theme the user has set in their client.

Value	Description
dark	Dark theme
light	Light theme

Explicit Content Filter

Whose messages will be scanned for explicit content.

Value	Name	Description
0	DISABLED	Don't scan any direct messages
1	NON_FRIENDS	Scan all direct messages that aren't from friends
2	ALL_MESSAGES	Scan all direct messages from everyone

Friend Discovery Flags

Determines how you get recommended friends.

Value	Name	Description
1 << 1	FIND_BY_PHONE	Whether the current user can be found by phone number
1 << 2	FIND_BY_EMAIL	Whether the current user can be found by email

Legacy Friend Source Flags Structure

Determines who can add the user as a friend.

Field	Type	Description
all?	boolean	Whether everyone can add user as friend
mutual_friends?	boolean	Whether mutual user friends add user as friend
mutual_guilds?	boolean	Whether any user from mutual guild can add user as friend

Legacy Guild Folder Structure

A collection of guilds.

Field	Type	Description
color	?integer	The color of the folder encoded as an integer representation of hexadecimal color code
guild_ids	array[snowflake]	The IDs of guilds this folder contains
id	?integer	The ID of the folder
name	?string	The name of the folder (default `', '.join(guild.name for guild in folder.guilds)`)

Consents Object

Contains the user's tracking feature consent status.

Consents Structure

This object is a map of consent types to their status.

Value	Description
personalization	Whether the user has consented to their data being used for personalization
usage_statistics ¹	Whether the user has consented to their data being used for usage statistics

¹ Only included when fetched from the Get User Consents endpoint.

Field	Type	Description
consented	boolean	Whether the user has consented to the feature

Email Settings Object

Email communication preferences.

Email Settings Structure

Field	Type	Description
initialized	boolean	Whether the email settings have been initialized
categories	map[string, boolean]	The email settings categories and their enabled status

Email Settings Category

Value	Description
communication	Receive emails for missed calls and messages
social	Receive emails for friend requests, friend suggestions, or events
recommendations_and_events	Receive emails for recommended guilds and events
tips	Receive emails for advice and tricks
updates_and_announcements	Receive emails for updates and new features
family_center_digest	Receive weekly emails for recent family activity

Notification Settings Object

User-wide notification settings.

Notification Settings Structure

Field	Type	Description
flags	integer	The notification settings flags

Notification Settings Flags

Value	Name	Description
1 << 4	USE_NEW_NOTIFICATIONS	Whether to separate unreads from the overall message notification level
1 << 5	MENTION_ON_ALL_MESSAGES	Whether to increment the mention count on all messages in channels with a message notification level of `ALL_MESSAGES`

Example Notification Settings

{ "flags": 16 }

Notification Settings Snapshot Object

A snapshot of the user's guild settings.

Notification Settings Snapshot Structure

Field	Type	Description
id	snowflake	The ID of the snapshot
label	?string	The label of the snapshot
recorded_at	ISO8601 timestamp	When the snapshot was recorded
length	integer	The length of the snapshot in bytes

Example Notification Settings Snapshot

{
  "id": "1189703042711425185",
  "label": "Before the Great Mute",
  "recorded_at": "2023-12-27T22:55:08.998082+00:00",
  "length": 145750
}

User Guild Settings Object

Guild-specific settings for the current user.

User Guild Settings Structure

Field	Type	Description
channel_overrides	array[channel override object]	The overrides for channels
flags	integer	The user guild settings flags
guild_id ¹	?snowflake	The ID of the guild
hide_muted_channels	boolean	Whether to hide muted channels from the UI
message_notifications	integer	The message notification level for the guild
mobile_push	boolean	Whether to send push notifications to mobile clients
mute_scheduled_events	boolean	Whether new guild scheduled event notifications are muted
muted	boolean	Whether the guild is muted
mute_config	?mute config object	The mute metadata for the guild
notify_highlights	integer	The highlight notification level for the guild
suppress_everyone	integer	Whether to suppress @everyone notifications
suppress_roles	integer	Whether to suppress role notifications
version	integer	The version of guild settings

¹ A value of null is used to indicate these settings are for the user's private channel notifications.

Partial User Guild Settings Structure

Used when modifying user guild settings.

Field	Type	Description
channel_overrides?	map[snowflake, channel override object]	The channel overrides to modify
flags?	integer	The user guild settings flags
hide_muted_channels?	boolean	Whether to hide muted channels from the UI
message_notifications?	integer	The message notification level for the guild
mobile_push?	boolean	Whether to send push notifications to mobile clients
mute_scheduled_events?	boolean	Whether new guild scheduled event notifications are muted
muted?	boolean	Whether the guild is muted
mute_config?	?mute config object	The mute metadata for the guild
notify_highlights?	integer	The highlight notification level for the guild
suppress_everyone?	integer	Whether to suppress @everyone notifications
suppress_roles?	integer	Whether to suppress role notifications

Channel Override Structure

Field	Type	Description
channel_id	snowflake	The ID of the channel
collapsed	boolean	Whether the category channel is collapsed
flags?	integer	The channel override's flags
message_notifications	integer	The message notification level for the channel
muted	boolean	Whether the channel is muted
mute_config	?mute config object	The mute metadata for the channel

Channel Override Flags

Value	Name	Description
1 << 9	UNREADS_ONLY_MENTIONS ¹	This channel is marked unread on mentions
1 << 10	UNREADS_ALL_MESSAGES ¹	This channel is marked unread on new messages
1 << 11	FAVORITED	This channel is favorited
1 << 12	OPT_IN_ENABLED	This channel is shown in the UI
1 << 13	NEW_FORUM_THREADS_OFF	This thread-only channel is not marked unread when a thread is created
1 << 14	NEW_FORUM_THREADS_ON	This thread-only channel is marked unread when a thread is created

¹ When these flags are unset, unreads follow the message_notifications field.

User Guild Settings Flags

Value	Name	Description
1 << 11	UNREADS_ALL_MESSAGES ¹	This guild is marked unread on new messages
1 << 12	UNREADS_ONLY_MENTIONS ¹	This guild is marked unread on mentions
1 << 13	OPT_IN_CHANNELS_OFF	Whether to show all guild channels in the UI
1 << 14	OPT_IN_CHANNELS_ON	Whether to hide non-opted in channels in the UI

¹ When these flags are unset, unreads follow the message_notifications field.

Highlight Level

Value	Name	Description
0	DEFAULT	Default (same as `ENABLED`)
1	DISABLED	Suppress highlights
2	ENABLED	Don't suppress highlights

Example User Guild Settings

{
  "guild_id": 373,
  "suppress_everyone": false,
  "suppress_roles": false,
  "mute_scheduled_events": false,
  "message_notifications": 1,
  "flags": 0,
  "mobile_push": true,
  "muted": true,
  "mute_config": {
    "end_time": null,
    "selected_time_window": -1
  },
  "hide_muted_channels": false,
  "channel_overrides": [
    {
      "channel_id": "362165922212872202",
      "message_notifications": 3,
      "muted": false,
      "mute_config": null,
      "collapsed": true
    }
  ],
  "notify_highlights": 0,
  "version": 2016
}

Mute Config Object

The duration of a mute.

Mute Config Structure

Field	Type	Description
end_time?	?ISO8601 timestamp	Timestamp representing when the mute ends
selected_time_window?	integer	Duration of the mute in seconds, or `-1` for indefinite

Endpoints

Get User Settings Proto

GET/users/@me/settings-proto/{type}

Returns the requester's user settings protobuf for the specified type.

Response Body

Field	Type	Description
settings	string	The base 64-encoded serialized user settings protobuf

Modify User Settings Proto

PATCH/users/@me/settings-proto/{type}

Modifies the requester's user settings protobuf for the specified type. Fires a User Settings Proto Update and User Settings Update Gateway event.

JSON Params

Field	Type	Description
settings	string	The base-64 encoded serialized user settings protobuf modifications
required_data_version? ¹	integer	The required data version of the proto

¹ When making offline edits, the required data version of the proto should be set to the last known version. This ensures that the client doesn't overwrite newer edits made on a different client on edit.

Response Body

Field	Type	Description
settings	string	The base-64 encoded serialized user settings protobuf
out_of_date?	boolean	Whether the user settings update was discarded due to an outdated `required_data_version`

Get User Settings

GET/users/@me/settings

Deprecated

Returns the requester's user settings object.

Modify User Settings

PATCH/users/@me/settings

OAuth2 Deprecated

Modifies the requester's user settings. Returns a user settings object on success. Fires a User Settings Proto Update and User Settings Update Gateway event.

JSON Params

Field	Type	Description
activity_joining_restricted_guild_ids?	array[snowflake]	The IDs of guilds that will not be able to join your current activity
activity_restricted_guild_ids?	array[snowflake]	The IDs of guilds your activity presence will be hidden in
afk_timeout?	integer	Duration (in seconds) the user needs to be inactive until clients update their AFK state
allow_accessibility_detection?	boolean	Whether to allow Discord to track screen reader usage
animate_emoji?	boolean	Whether to play animated emojis in chat
animate_stickers?	integer	When to animate stickers in chat
contact_sync_enabled?	boolean	Whether to enable contact sync on Discord mobile
convert_emoticons?	boolean	Whether to convert emoticons into emojis (`:)` -> `🙂`)
custom_status?	?custom status object	The custom status of the user, used to sync presence across clients
default_guilds_restricted?	boolean	Whether to automatically disable DMs between you and members of new guilds you join
detect_platform_accounts?	boolean	Whether to automatically detect accounts from services like Steam and Blizzard when opening the Discord client
developer_mode?	boolean	Whether to enable developer mode in-client
disable_games_tab?	boolean	Whether to disable the showing of the Games tab
enable_tts_command?	boolean	Whether to allow TTS messages to be played/sent
explicit_content_filter?	integer	The explicit content filter for explicit content in all messages
friend_discovery_flags?	integer	The friend discovery flags
friend_source_flags?	friend source flags object	The friend source flags
gif_auto_play?	boolean	Whether GIFs are automatically played when Discord client is in focus
guild_folders?	array[guild folder object]	The guild folders
inline_attachment_media?	boolean	Whether to display attachments when they are uploaded in chat
inline_embed_media?	boolean	Whether to display videos and images from links posted in chat
locale?	string	The language option chosen by the user
message_display_compact?	boolean	Whether to use the compact Discord display mode
native_phone_integration_enabled?	boolean	Whether to enable the new Discord mobile phone number friend requesting feature
passwordless? (deprecated)	boolean	Whether to enable passwordless login
render_embeds?	boolean	Whether to render message embeds
render_reactions?	boolean	Whether to render message reactions
restricted_guilds?	array[snowflake]	The IDs of guilds that you will not receive DMs from
show_current_game?	boolean	Whether to display the currently active game in user presence
status?	string	The status of the user, used to sync presence across clients
stream_notifications_enabled?	boolean	Whether to receive stream notifications for friends
theme?	string	The theme
timezone_offset?	integer	The timezone offset from UTC to use (in minutes)
view_nsfw_guilds?	boolean	Whether NSFW guilds are shown on iOS

Field	Type	Description
grant	array[string]	The consent types to grant
revoke	array[string]	The consent types to revoke

Field	Type	Description
settings	partial email settings object	The email settings to modify

Modify Notification Settings

PATCH/users/@me/notification-settings

Replaces the notification settings for the user. Returns a notification settings object on success. Fires a Notification Settings Update Gateway event.

JSON Params

Field	Type	Description
flags?	?integer	The notification settings flags to set

Field	Type	Description
label?	?string	The label of the snapshot (max 100 characters)

Field	Type	Description
guilds	map[snowflake, partial user guild settings object]	The user guild settings to modify