Update subscription settings
POST https://chat.futo.org/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://chat.futo.org/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"
}