Update subscription settings
POST https://cs-a1120-2024.zulip.aalto.fi/api/v1/users/me/subscriptions/properties
This endpoint is used to update the user's personal settings for the
streams they are subscribed to, including muting, color, pinning, and
per-stream notification settings.
Changes: Prior to Zulip 5.0 (feature level 111), response
object included the subscription_data in the the
request. The endpoint now returns the more ergonomic
ignored_parameters_unsupported array instead.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# Update the user's subscription in stream #1 to pin it to the top of the
# stream list; and in stream #3 to have the hex color "f00"
request = [
{
"stream_id": 1,
"property": "pin_to_top",
"value": True,
},
{
"stream_id": 7,
"property": "color",
"value": "#f00f00",
},
]
result = client.update_subscription_settings(request)
print(result)
curl -sSX POST https://cs-a1120-2024.zulip.aalto.fi/api/v1/users/me/subscriptions/properties \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'subscription_data=[{"property": "pin_to_top", "stream_id": 1, "value": true}, {"property": "color", "stream_id": 3, "value": "#f00f00"}]'
Parameters
subscription_data (object)[] required
Example: [{"stream_id": 1, "property": "pin_to_top", "value": true}, {"stream_id": 3, "property": "color", "value": "#f00f00"}]
A list of objects that describe the changes that should be applied in
each subscription. Each object represents a subscription, and must have
a stream_id key that identifies the stream, as well as the property
being modified and its new value.
subscription_data object details:
-
stream_id: integer required The unique ID of a stream.
-
property: string required One of the stream properties described below:
-
"color": The hex value of the user's display color for the stream.
-
"is_muted": Whether the stream is muted.
Changes: As of Zulip 6.0 (feature level 139), updating either
"is_muted" or "in_home_view" generates two subscription update
events, one for each property,
that are sent to clients. Prior to this feature level, updating either
property only generated a subscription update event for
"in_home_view".
Changes: Prior to Zulip 2.1.0, this feature was represented
by the more confusingly named "in_home_view" (with the
opposite value: in_home_view=!is_muted); for
backwards-compatibility, modern Zulip still accepts that property.
-
"pin_to_top": Whether to pin the stream at the top of the stream list.
-
"desktop_notifications": Whether to show desktop notifications
for all messages sent to the stream.
-
"audible_notifications": Whether to play a sound
notification for all messages sent to the stream.
-
"push_notifications": Whether to trigger a mobile push
notification for all messages sent to the stream.
-
"email_notifications": Whether to trigger an email
notification for all messages sent to the stream.
-
"wildcard_mentions_notify": Whether wildcard mentions trigger
notifications as though they were personal mentions in this stream.
Must be one of: "color", "is_muted", "in_home_view", "pin_to_top", "desktop_notifications", "audible_notifications", "push_notifications", "email_notifications", "wildcard_mentions_notify".
-
value: boolean | string required The new value of the property being modified.
If the property is "color", then value is a string
representing the hex value of the user's display
color for the stream. For all other above properties,
value is a boolean.
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"
}