Update subscription settings

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.

POST https://hott.zulipchat.com/api/v1/users/me/subscriptions/properties

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 ergonimic ignored_parameters_unsupported field 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://hott.zulipchat.com/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.

The possible values for each property and value pairs are:

  • color (string): The hex value of the user's display color for the stream.
  • is_muted (boolean): Whether the stream is muted.
    Changes: Prior to Zulip 2.1, 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 (boolean): Whether to pin the stream at the top of the stream list.
  • desktop_notifications (boolean): Whether to show desktop notifications for all messages sent to the stream.
  • audible_notifications (boolean): Whether to play a sound notification for all messages sent to the stream.
  • push_notifications (boolean): Whether to trigger a mobile push notification for all messages sent to the stream.
  • email_notifications (boolean): Whether to trigger an email notification for all messages sent to the stream.
  • wildcard_mentions_notify (boolean): Whether wildcard mentions trigger notifications as though they were personal mentions in this stream.

Response

Return values

  • ignored_parameters_unsupported: (string)[] An array of any parameters sent in the request that are not supported by the endpoint. While this can be expected, e.g. when sending both current and legacy names for a parameter to a Zulip server of unknown version, this often indicates either a bug in the client implementation or an attempt to configure a new feature while connected to an older Zulip server that does not support said feature.

    Changes: Added to POST /users/me/subscriptions/properties in Zulip 5.0 (feature level 111).

    Added to PATCH /realm/user_settings_defaults in Zulip 5.0 (feature level 96).

    Introduced in PATCH /settings in Zulip 5.0 (feature level 78).

Example response

A typical successful JSON response may look like:

{
    "ignored_parameters_unsupported": [
        "invalid_parameter"
    ],
    "msg": "",
    "result": "success"
}