Update settings
PATCH https://chat.futo.org/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).
The /settings/display
and /settings/notifications
endpoints are now deprecated aliases for this endpoint for
backwards-compatibility, and will be removed once clients have
migrated to use this endpoint.
Changes: Prior to Zulip 5.0 (feature level 78),
the /settings
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 /settings/notifications
and /settings/display
endpoints
also had this behavior before they became aliases of /settings
in Zulip 5.0 (see feature level 80 change above).
Before these changes, request parameters that were not supported
(or were unchanged) were silently ignored.
Usage examples
#!/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://chat.futo.org/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
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.
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.
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.
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" - All messages 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 streams 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_stream_unreads_count_display_policy integer optional
Example: 2
Configuration for which streams should be displayed with a numeric unread count in the left sidebar.
Streams that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All streams
- 2 - Unmuted streams and topics
- 3 - No streams
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 stream 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 stream 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 stream 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 stream 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 streams.
- 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
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).
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
.
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"
}