Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Drafts

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

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://z.labs.greyorange.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 ergonomic ignored_parameters_unsupported field instead.

Usage examples

  • Python
  • curl

#!/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://z.labs.greyorange.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.

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: 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": 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

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"
}