Update personal preferences for a topic

POST https://mylog.connect.xfel.eu/api/v1/user_topics

This endpoint is used to update the personal preferences for a topic, such as the topic's visibility policy, which is used to implement mute a topic and related features.

This endpoint can be used to update the visibility policy for the single stream and topic pair indicated by the parameters for a user.

Changes: New in Zulip 7.0 (feature level 170). Previously, toggling the muting state for a topic was managed by the /users/me/subscriptions/muted_topics endpoint, which this endpoint is intended to replace.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Mute the topic "dinner" in the stream having id 'stream_id'.
request = {
    "stream_id": stream_id,
    "topic": "dinner",
    "visibility_policy": 1,
}
result = client.call_endpoint(
    url="user_topics",
    method="POST",
    request=request,
)
# Remove mute from the topic "dinner" in the stream having id 'stream_id'.
request = {
    "stream_id": stream_id,
    "topic": "dinner",
    "visibility_policy": 0,
}

result = client.call_endpoint(
    url="user_topics",
    method="POST",
    request=request,
)
print(result)

curl -sSX POST https://mylog.connect.xfel.eu/api/v1/user_topics \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode stream_id=1 \
    --data-urlencode topic=dinner \
    --data-urlencode visibility_policy=1

Parameters

stream_id integer required

Example: 1

The ID of the stream to access.


topic string required

Example: "dinner"

The topic for which the personal preferences needs to be updated. Note that the request will succeed regardless of whether any messages have been sent to the specified topic.


visibility_policy integer required

Example: 1

Controls which visibility policy to set.

  • 0 - INHERIT
  • 1 - MUTED
  • 2 - UNMUTED

The visibility policy, when set to MUTED, mutes a topic; when set to UNMUTED, it unmutes a topic in a muted stream; and INHERIT is used to remove the visibility policy already set.

MUTED topics are displayed faded in the Zulip UI, are not included in the user's unread count totals, and the user doesn't receive any notifications.

An UNMUTED topic will remain visible even if the stream is muted. In a stream that is not muted, a policy of UNMUTED has the same effect as INHERIT.

Must be one of: 0, 1, 2.


Response

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success"
}