User settings¶

User settings cover the account-wide preferences and the notification settings kept for each guild and for private channels.

Every route on this page requires a user session. A valid bot token is rejected with 403 ACCESS_DENIED.

Presence status values¶

offline describes an account with no active session and cannot be stored.

Theme values¶

Notification levels¶

Mute configuration object¶

When no mute configuration is stored, responses contain {"end_time": null, "selected_time_window": null}. An end_time in the past no longer mutes but can remain in the response.

Channel notification override object¶

Notification settings for one channel.

Fields that were never written are returned as null.

User guild settings object¶

Notification settings for one guild, or for all direct messages and group DMs when guild_id is null.

{
  "guild_id": null,
  "message_notifications": 1,
  "muted": false,
  "mute_config": { "end_time": null, "selected_time_window": 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¶

The body of Modify guild notification settings. Every field is optional, and an omitted field is left unchanged.

Mute configuration input object¶

Channel override input object¶

Map keys must be channel IDs; a non-numeric key returns 400.

User settings update object¶

The body of Modify current user settings. Every field is optional. An omitted field is left unchanged; a field that is present is validated and written, and an invalid value fails the whole request with 400 (TEBHOS never silently skips a field). The fields may also be wrapped as {"settings": {...}}.

Snowflake arrays accept string or numeric IDs; duplicates are removed.

Locale codes: ar, bg, cs, da, de, el, en-GB, en-US, es-ES, es-419, fi, fr, he, hi, hr, hu, id, it, ja, ko, lt, nl, no, pl, pt-BR, ro, ru, sv-SE, th, tr, uk, vi, zh-CN, zh-TW. The TEBHOS web client is currently translated into en-US and tr; see Locales.

Guild folder input object¶

When the submitted layout has no uncategorised folder, an empty one is prepended. A guild ID that appears more than once is kept in only one place: a folder with a non-blank name beats an unnamed one, an ordinary folder beats the uncategorised folder, and the earliest occurrence wins a tie. Keep guild IDs you cannot render in the array; anything you leave out is removed from the stored layout.

Custom status input object¶

An object with neither text nor emoji clears the status. The emoji ID is stored as given and is not resolved.

Initial settings¶

TEBHOS does not write a settings record at sign-up; a field that was never written is returned with this value.

Get current user settings¶

GET /users/@me/settings

Returns the user settings object. An account that never changed a setting receives the initial values.

Rate limit¶

40 requests per 10 seconds per user, bucket user:settings:get, shared with Get current user.

curl https://tebhos.com/api/v1/users/@me/settings \
  -H "Authorization: Bearer $TEBHOS_TOKEN"

Modify current user settings¶

PATCH /users/@me/settings

Applies the user settings update object and returns the complete user settings object. PUT behaves the same way.

Response¶

Side effects¶

The caller's sessions receive USER_SETTINGS_UPDATE with the full settings object, even when nothing changed. The Gateway applies the custom status to the caller's presence. A status of invisible switches every session of the caller to invisible, and a later online, idle or dnd reverses that. See Gateway events.

Rate limit¶

20 requests per 10 seconds per user, bucket user:settings:update, shared with Modify voice activity sharing.

curl -X PATCH https://tebhos.com/api/v1/users/@me/settings \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "dnd", "custom_status": {"text": "Focusing", "emoji_name": "🎧"}}'

Modify voice activity sharing¶

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

Sets the default voice activity sharing value, applies it to the caller's side of every friendship, and returns the caller's user object.

JSON body¶

Cooldown¶

The value can change once every 24 hours. A request inside the window, including one that repeats the current value, fails with 429 and a Retry-After header holding the remaining seconds. last_voice_activity_sharing_change_at on the user object records the last accepted change.

Response¶

Side effects¶

For every friendship, the caller and the friend each receive RELATIONSHIP_UPDATE. The caller receives USER_UPDATE, and USER_SETTINGS_UPDATE when the stored default changed.

Rate limit¶

20 requests per 10 seconds per user, bucket user:settings:update.

List guild notification settings¶

GET /users/@me/guilds/settings

Returns an array of every stored user guild settings object, including the private channel settings when they were written.

Get guild notification settings¶

GET /users/@me/guilds/{guild_id}/settings

Returns the user guild settings object for one guild. Use @me (or 0) as guild_id for direct message and group DM settings. Settings that were never written are returned with their defaults and version 0.

Modify guild notification settings¶

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

Applies the guild settings update fields and returns the resulting user guild settings object. Use @me (or 0) as guild_id for the private channel settings, which are returned with guild_id null. Settings are created with defaults when absent.

Side effects¶

The caller's sessions receive USER_GUILD_SETTINGS_UPDATE with the settings object plus user_id, on every successful write.

Rate limit¶

30 requests per 10 seconds per user, bucket user:guild_settings:update.

curl -X PATCH https://tebhos.com/api/v1/users/@me/guilds/1501314428688998100/settings \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message_notifications": 1, "suppress_everyone": true}'

Legacy settings views¶

The TEBHOS web client's older settings tabs read and write compatibility views of the same settings record. New integrations should use the routes above.

A change through one of these views updates the mapped fields of the user settings object and emits USER_SETTINGS_UPDATE.