Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Drafts

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Update realm-level defaults of user settings

This endpoint is only available to organization administrators.

Change the default values of settings for new users joining the organization. Essentially all personal preference settings are supported.

PATCH https://main.zulip.pr.business/api/v1/realm/user_settings_defaults

This feature can be invaluable for customizing Zulip's default settings for notifications or UI to be appropriate for how the organization is using Zulip. (Note that this only supports personal preference settings, like when to send push notifications or what emoji set to use, not profile or identity settings that naturally should be different for each user).

Note that this endpoint cannot, at present, be used to modify settings for existing users in any way.

Changes: New in Zulip 5.0 (feature level 96).

Usage examples

  • curl

curl -sSX PATCH https://main.zulip.pr.business/api/v1/realm/user_settings_defaults \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode left_side_userlist=true \
    --data-urlencode emojiset=google

Parameters

dense_mode boolean optional

Example: true

This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip.

starred_message_counts boolean optional

Example: true

Whether clients should display the number of starred messages.

fluid_layout_width boolean optional

Example: true

Whether to use the maximum available screen width for the web app's center panel (message feed, recent topics) on wide screens.

high_contrast_mode boolean optional

Example: true

This setting is reserved for use to control variations in Zulip's design to help visually impaired users.

color_scheme integer optional

Example: 1

Controls which color theme to use.

  • 1 - Automatic
  • 2 - Dark theme
  • 3 - Light theme

Automatic detection is implementing using the standard prefers-color-scheme media query.

Must be one of: 1, 2, 3.

enable_drafts_synchronization boolean optional

Example: true

A boolean parameter to control whether synchronizing drafts is enabled for the user. When synchronization is disabled, all drafts stored in the server will be automatically deleted from the server.

This does not do anything (like sending events) to delete local copies of drafts stored in clients.

translate_emoticons boolean optional

Example: true

Whether to translate emoticons to emoji in messages the user sends.

default_view string optional

Example: "all_messages"

The default view used when opening a new Zulip web app window or hitting the Esc keyboard shortcut repeatedly.

  • "recent_topics" - Recent topics view
  • "all_messages" - All messages view

escape_navigates_to_default_view boolean optional

Example: true

Whether the escape key navigates to the configured default view.

Changes: New in Zulip 5.0 (feature level 107).

left_side_userlist boolean optional

Example: true

Whether the users list on left sidebar in narrow windows.

This feature is not heavily used and is likely to be reworked.

emojiset string optional

Example: "google"

The user's configured emoji set, used to display emoji to the user everywhere they appear in the UI.

  • "google" - Google modern
  • "google-blob" - Google classic
  • "twitter" - Twitter
  • "text" - Plain text

demote_inactive_streams integer optional

Example: 1

Whether to demote inactive streams in the left sidebar.

  • 1 - Automatic
  • 2 - Always
  • 3 - Never

Must be one of: 1, 2, 3.

enable_stream_desktop_notifications boolean optional

Example: true

Enable visual desktop notifications for stream messages.

enable_stream_email_notifications boolean optional

Example: true

Enable email notifications for stream messages.

enable_stream_push_notifications boolean optional

Example: true

Enable mobile notifications for stream messages.

enable_stream_audible_notifications boolean optional

Example: true

Enable audible desktop notifications for stream messages.

notification_sound string optional

Example: "ding"

Notification sound name.

enable_desktop_notifications boolean optional

Example: true

Enable visual desktop notifications for private messages and @-mentions.

enable_sounds boolean optional

Example: true

Enable audible desktop notifications for private messages and @-mentions.

email_notifications_batching_period_seconds integer optional

Example: 120

The duration (in seconds) for which the server should wait to batch email notifications before sending them.

enable_offline_email_notifications boolean optional

Example: true

Enable email notifications for private messages and @-mentions received when the user is offline.

enable_offline_push_notifications boolean optional

Example: true

Enable mobile notification for private messages and @-mentions received when the user is offline.

enable_online_push_notifications boolean optional

Example: true

Enable mobile notification for private messages and @-mentions received when the user is online.

enable_digest_emails boolean optional

Example: true

Enable digest emails when the user is away.

message_content_in_email_notifications boolean optional

Example: true

Include the message's content in email notifications for new messages.

pm_content_in_desktop_notifications boolean optional

Example: true

Include content of private messages in desktop notifications.

wildcard_mentions_notify boolean optional

Example: true

Whether wildcard mentions (E.g. @all) should send notifications like a personal mention.

desktop_icon_count_display integer optional

Example: 1

Unread count badge (appears in desktop sidebar and browser tab)

  • 1 - All unreads
  • 2 - Private messages and mentions
  • 3 - None

Must be one of: 1, 2, 3.

realm_name_in_notifications boolean optional

Example: true

Include organization name in subject of message notification emails.

presence_enabled boolean optional

Example: true

Display the presence status to other users when online.

enter_sends boolean optional

Example: true

Whether pressing Enter in the compose box sends a message (or saves a message edit).

twenty_four_hour_time boolean optional

Example: true

Whether time should be displayed in 24-hour notation.

Changes: New in Zulip 5.0 (feature level 99). Previously, this default was edited using the default_twenty_four_hour_time parameter to the PATCH /realm endpoint.

send_private_typing_notifications boolean optional

Example: true

Whether typing notifications be sent when composing private messages.

Changes: New in Zulip 5.0 (feature level 105).

send_stream_typing_notifications boolean optional

Example: true

Whether typing notifications be sent when composing stream messages.

Changes: New in Zulip 5.0 (feature level 105).

send_read_receipts boolean optional

Example: true

Whether other users are allowed to see whether you've read messages.

Changes: New in Zulip 5.0 (feature level 105).

Response

Return values

  • ignored_parameters_unsupported: (string)[]

    An array of any parameters sent in the request that are not supported by the endpoint. While this can be expected, e.g. when sending both current and legacy names for a parameter to a Zulip server of unknown version, this often indicates either a bug in the client implementation or an attempt to configure a new feature while connected to an older Zulip server that does not support said feature.

    Changes: Added to POST /users/me/subscriptions/properties in Zulip 5.0 (feature level 111).

    Added to PATCH /realm/user_settings_defaults in Zulip 5.0 (feature level 96).

    Introduced in PATCH /settings in Zulip 5.0 (feature level 78).

Example response

A typical successful JSON response may look like:

{
    "ignored_parameters_unsupported": [
        "desktop_notifications",
        "demote_streams"
    ],
    "msg": "",
    "result": "success"
}