Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

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://zulip.d4science.org/api/v1/users/me/subscriptions/properties

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': 3,
    'property': 'color',
    'value': 'f00'
}]
result = client.update_subscription_settings(request)
print(result)


curl -X POST https://zulip.d4science.org/api/v1/users/me/subscriptions/properties \
     -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
     -d 'subscription_data=[{"stream_id": 1, \
                             "property": "pin_to_top", \
                             "value": true}, \
                            {"stream_id": 3, \
                             "property": "color", \
                             "value": 'f00'}]'

Arguments

Argument Example Required Description
subscription_data [{"stream_id":1,"value":true,"property":"pin_to_top"}] 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.

Response

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