Update subscription settings

POST https://tilastotieteen-perusteet-k2023.zulip.aalto.fi/api/v1/users/me/subscriptions/properties

This endpoint is used to update the user's personal settings for the channels they are subscribed to, including muting, color, pinning, and per-channel notification settings.

Changes: Prior to Zulip 5.0 (feature level 111), response object included the subscription_data in the request. The endpoint now returns the more ergonomic ignored_parameters_unsupported array 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 of the channel with ID `stream_a_id`
# so that it's pinned to the top of the user's channel list, and in
# the channel with ID `stream_b_id` so that it has the hex color "f00".
request = [
    {
        "stream_id": stream_a_id,
        "property": "pin_to_top",
        "value": True,
    },
    {
        "stream_id": stream_b_id,
        "property": "color",
        "value": "#f00f00",
    },
]
result = client.update_subscription_settings(request)
print(result)

curl -sSX POST https://tilastotieteen-perusteet-k2023.zulip.aalto.fi/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 channel, as well as the property being modified and its new value.

subscription_data object details:

stream_id: integer required
The unique ID of a channel.
property: string required
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
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.
This parameter must be one of the following:

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

Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Scheduled messages

Drafts

Channels

Users

Invitations

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Update subscription settings

Usage examples

Parameters

Response

Example response(s)