Update subscription 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.

POST https://yourZulipDomain.zulipchat.com/api/v1/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 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': 3,
    'property': 'color',
    'value': 'f00'
result = client.update_subscription_settings(request)

curl -X POST https://yourZulipDomain.zulipchat.com/api/v1/users/me/subscriptions/properties \
     -d 'subscription_data=[{"stream_id": 1, \
                             "property": "pin_to_top", \
                             "value": true}, \
                            {"stream_id": 3, \
                             "property": "color", \
                             "value": 'f00'}]'


Argument Example Required Description
subscription_data [{"property":"pin_to_top","stream_id":1,"value":true}] Yes

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.
  • in_home_view (boolean): whether the stream should be visible in the home view (true) or muted and thus hidden from the home view (false).
  • 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.


Return values

  • subscription_data: The same subscription_data object sent by the client for the request, confirming the changes made.

Example response

A typical successful JSON response may look like:

    "msg": "",
    "result": "success",
    "subscription_data": [
            "property": "pin_to_top",
            "stream_id": 1,
            "value": true
            "property": "color",
            "stream_id": 3,
            "value": "f00"