Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Scheduled messages

Drafts

Channels

Users

Invitations

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Update settings

PATCH https://developing-today.zulipchat.com/api/v1/settings

This endpoint is used to edit the current user's settings.

Changes: Prior to Zulip 5.0 (feature level 80), this endpoint only supported the full_name, email, old_password, and new_password parameters. Notification settings were managed by PATCH /settings/notifications, and all other settings by PATCH /settings/display.

The feature level 80 migration to merge these endpoints did not change how request parameters are encoded. However, it did change the handling of any invalid parameters present in a request (see feature level 78 change below).

As of feature level 80, the PATCH /settings/display and PATCH /settings/notifications endpoints are deprecated aliases for this endpoint for backwards-compatibility, and will be removed once clients have migrated to use this endpoint.

Prior to Zulip 5.0 (feature level 78), this endpoint indicated which parameters it had processed by including in the response object "key": value entries for values successfully changed by the request. That was replaced by the more ergonomic ignored_parameters_unsupported array.

The PATCH /settings/notifications and PATCH /settings/display endpoints also had this behavior of indicating processed parameters before they became aliases of this endpoint in Zulip 5.0 (see feature level 80 change above).

Before feature level 78, request parameters that were not supported (or were unchanged) were silently ignored.

Usage examples

  • Python
  • curl

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Enable push notifications even when online and change emoji set.
request = {
    "enable_offline_push_notifications": True,
    "enable_online_push_notifications": True,
    "emojiset": "google",
}
result = client.call_endpoint("/settings", method="PATCH", request=request)
print(result)


curl -sSX PATCH https://developing-today.zulipchat.com/api/v1/settings \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode left_side_userlist=true \
    --data-urlencode emojiset=google

Parameters

full_name string optional

Example: "NewName"

A new display name for the user.

email string optional

Example: "newname@example.com"

Asks the server to initiate a confirmation sequence to change the user's email address to the indicated value. The user will need to demonstrate control of the new email address by clicking a confirmation link sent to that address.

old_password string optional

Example: "old12345"

The user's old Zulip password (or LDAP password, if LDAP authentication is in use).

Required only when sending the new_password parameter.

new_password string optional

Example: "new12345"

The user's new Zulip password (or LDAP password, if LDAP authentication is in use).

The old_password parameter must be included in the request.

twenty_four_hour_time boolean optional

Example: true

Whether time should be displayed in 24-hour notation.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

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.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

web_mark_read_on_scroll_policy integer optional

Example: 1

Whether or not to mark messages as read when the user scrolls through their feed.

  • 1 - Always
  • 2 - Only in conversation views
  • 3 - Never

Changes: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read.

Must be one of: 1, 2, 3.

web_channel_default_view integer optional

Example: 1

Web/desktop app setting controlling the default navigation behavior when clicking on a channel link.

  • 1 - Top topic in the channel
  • 2 - Channel feed

Changes: New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior.

Must be one of: 1, 2.

starred_message_counts boolean optional

Example: true

Whether clients should display the number of starred messages.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

receives_typing_notifications boolean optional

Example: true

Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled.

By default, this is set to true, enabling user to receive typing notifications from other users.

Changes: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications.

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 conversations) on wide screens.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

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.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

web_font_size_px integer optional

Example: 14

User-configured primary font-size for the web application, in pixels.

Changes: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level.

web_line_height_percent integer optional

Example: 122

User-configured primary line-height for the web application, in percent, so a value of 120 represents a line-height of 1.2.

Changes: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level.

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.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

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.

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

translate_emoticons boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

display_emoji_reaction_users boolean optional

Example: false

Whether to display the names of reacting users on a message.

When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled.

Changes: New in Zulip 6.0 (feature level 125).

default_language string optional

Example: "en"

What default language to use for the account.

This controls both the Zulip UI as well as email notifications sent to the user.

The value needs to be a standard language code that the Zulip server has translation data for; for example, "en" for English or "de" for German.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).

web_home_view string optional

Example: "all_messages"

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

  • "recent_topics" - Recent conversations view
  • "inbox" - Inbox view
  • "all_messages" - Combined feed view

Changes: New in Zulip 8.0 (feature level 219). Previously, this was called default_view, which was new in Zulip 4.0 (feature level 42).

Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).

web_escape_navigates_to_home_view boolean optional

Example: true

Whether the escape key navigates to the configured home view.

Changes: New in Zulip 8.0 (feature level 219). Previously, this was called escape_navigates_to_default_view, which was 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.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).

demote_inactive_streams integer optional

Example: 1

Whether to demote inactive channels in the left sidebar.

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

Must be one of: 1, 2, 3.

user_list_style integer optional

Example: 1

The style selected by the user for the right sidebar user list.

  • 1 - Compact
  • 2 - With status
  • 3 - With avatar and status

Changes: New in Zulip 6.0 (feature level 141).

Must be one of: 1, 2, 3.

web_animate_image_previews string optional

Example: "on_hover"

Controls how animated images should be played in the message feed in the web/desktop application.

  • "always" - Always play the animated images in the message feed.
  • "on_hover" - Play the animated images on hover over them in the message feed.
  • "never" - Never play animated images in the message feed.

Changes: New in Zulip 9.0 (feature level 275).

Must be one of: "always", "on_hover", "never".

web_stream_unreads_count_display_policy integer optional

Example: 2

Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages.

  • 1 - All channels
  • 2 - Unmuted channels and topics
  • 3 - No channels

Changes: New in Zulip 8.0 (feature level 210).

Must be one of: 1, 2, 3.

timezone string optional

Example: "Asia/Kolkata"

The IANA identifier of the user's configured time zone.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/display endpoint.

Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).

enable_stream_desktop_notifications boolean optional

Example: true

Enable visual desktop notifications for channel messages.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_stream_email_notifications boolean optional

Example: true

Enable email notifications for channel messages.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_stream_push_notifications boolean optional

Example: true

Enable mobile notifications for channel messages.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_stream_audible_notifications boolean optional

Example: true

Enable audible desktop notifications for channel messages.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

notification_sound string optional

Example: "ding"

Notification sound name.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).

enable_desktop_notifications boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_sounds boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

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.

Changes: New in Zulip 5.0 (feature level 82)

enable_offline_email_notifications boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_offline_push_notifications boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_online_push_notifications boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_followed_topic_desktop_notifications boolean optional

Example: true

Enable visual desktop notifications for messages sent to followed topics.

Changes: New in Zulip 8.0 (feature level 189).

enable_followed_topic_email_notifications boolean optional

Example: true

Enable email notifications for messages sent to followed topics.

Changes: New in Zulip 8.0 (feature level 189).

enable_followed_topic_push_notifications boolean optional

Example: false

Enable push notifications for messages sent to followed topics.

Changes: New in Zulip 8.0 (feature level 189).

enable_followed_topic_audible_notifications boolean optional

Example: false

Enable audible desktop notifications for messages sent to followed topics.

Changes: New in Zulip 8.0 (feature level 189).

enable_digest_emails boolean optional

Example: true

Enable digest emails when the user is away.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_marketing_emails boolean optional

Example: true

Enable marketing emails. Has no function outside Zulip Cloud.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_login_emails boolean optional

Example: true

Enable email notifications for new logins to account.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

message_content_in_email_notifications boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

pm_content_in_desktop_notifications boolean optional

Example: true

Include content of direct messages in desktop notifications.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

wildcard_mentions_notify boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enable_followed_topic_wildcard_mentions_notify boolean optional

Example: true

Whether wildcard mentions (e.g., @all) in messages sent to followed topics should send notifications like a personal mention.

Changes: New in Zulip 8.0 (feature level 189).

desktop_icon_count_display integer optional

Example: 1

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

  • 1 - All unread messages
  • 2 - DMs, mentions, and followed topics
  • 3 - DMs and mentions
  • 4 - None

Changes: In Zulip 8.0 (feature level 227), added DMs, mentions, and followed topics option, renumbering the options to insert it in order.

Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

Must be one of: 1, 2, 3, 4.

realm_name_in_email_notifications_policy integer optional

Example: 1

Whether to include organization name in subject of message notification emails.

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

Changes: New in Zulip 7.0 (feature level 168), replacing the previous realm_name_in_notifications boolean; true corresponded to Always, and false to Never.

Before Zulip 5.0 (feature level 80), the previous realm_name_in_notifications setting was managed by the PATCH /settings/notifications endpoint.

Must be one of: 1, 2, 3.

automatically_follow_topics_policy integer optional

Example: 1

Which topics to follow automatically.

  • 1 - Topics the user participates in
  • 2 - Topics the user sends a message to
  • 3 - Topics the user starts
  • 4 - Never

Changes: New in Zulip 8.0 (feature level 214).

Must be one of: 1, 2, 3, 4.

automatically_unmute_topics_in_muted_streams_policy integer optional

Example: 1

Which topics to unmute automatically in muted channels.

  • 1 - Topics the user participates in
  • 2 - Topics the user sends a message to
  • 3 - Topics the user starts
  • 4 - Never

Changes: New in Zulip 8.0 (feature level 214).

Must be one of: 1, 2, 3, 4.

automatically_follow_topics_where_mentioned boolean optional

Example: true

Whether the server will automatically mark the user as following topics where the user is mentioned.

Changes: New in Zulip 8.0 (feature level 235).

presence_enabled boolean optional

Example: true

Display the presence status to other users when online.

Changes: Before Zulip 5.0 (feature level 80), this setting was managed by the PATCH /settings/notifications endpoint.

enter_sends boolean optional

Example: true

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

Changes: Before Zulip 5.0 (feature level 81), this setting was managed by the POST /users/me/enter-sends endpoint, with the same parameter format.

send_private_typing_notifications boolean optional

Example: true

Whether typing notifications be sent when composing direct 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 channel 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).

allow_private_data_export boolean optional

Example: true

Whether organization administrators are allowed to export your private data.

Changes: New in Zulip 10.0 (feature level 293).

email_address_visibility integer optional

Example: 1

The policy this user has selected for which other users in this organization can see their real email address.

  • 1 = Everyone
  • 2 = Members only
  • 3 = Administrators only
  • 4 = Nobody
  • 5 = Moderators only

Changes: New in Zulip 7.0 (feature level 163), replacing the realm-level setting.

Must be one of: 1, 2, 3, 4, 5.

web_navigate_to_sent_message boolean optional

Example: true

Web/desktop app setting for whether the user's view should automatically go to the conversation where they sent a message.

Changes: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable.

Response

Example response(s)

Changes: The ignored_parameters_unsupported array was added as a possible return value for all REST API endpoint JSON success responses in Zulip 7.0 (feature level 167).

Previously, it was added to POST /users/me/subscriptions/properties in Zulip 5.0 (feature level 111) and to PATCH /realm/user_settings_defaults in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0 (feature level 78) as a return value for the PATCH /settings endpoint.

A typical successful JSON response with ignored parameters may look like:

{
    "ignored_parameters_unsupported": [
        "invalid_param_1",
        "invalid_param_2"
    ],
    "msg": "",
    "result": "success"
}

Your feedback helps us make Zulip better for everyone! Please contact us with questions, suggestions, and feature requests.