Update a subscription setting
PATCH https://datahandwerk.zulipchat.com/api/v1/users/me/subscriptions/{stream_id}
Update the current user's personal settings for a specific channel they
are subscribed to. These settings include color,
muting, pinning
and per-channel notification settings.
This is a single channel alternative to the bulk endpoint:
POST /users/me/subscriptions/properties.
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 of the channel with ID `stream_id`
# so that it's pinned to the top of the user's channel list.
request = {
"property": "pin_to_top",
"value": True,
}
result = client.call_endpoint(
f"users/me/subscriptions/{stream_id}",
method="PATCH",
request=request,
)
print(result)
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Zulip users and bots.
curl -sSX PATCH https://datahandwerk.zulipchat.com/api/v1/users/me/subscriptions/1 \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode property=pin_to_top \
--data-urlencode value=true
Parameters
stream_id integer required in path
Example: 1
The ID of the channel to access.
property string required
Example: "pin_to_top"
One of the channel properties described below:
-
"color": The hex value of the user's display color for the channel.
-
"is_muted": Whether the channel 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".
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 channel at the top of the channel list.
-
"desktop_notifications": Whether to show desktop notifications
for all messages sent to the channel.
-
"audible_notifications": Whether to play a sound
notification for all messages sent to the channel.
-
"push_notifications": Whether to trigger a mobile push
notification for all messages sent to the channel.
-
"email_notifications": Whether to trigger an email
notification for all messages sent to the channel.
-
"wildcard_mentions_notify": Whether wildcard mentions trigger
notifications as though they were personal mentions in this channel.
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
Example: "true"
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 channel. For all other above properties,
value is a boolean.
Response
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"msg": "",
"result": "success"
}