Update personal preferences for a topic

POST https://ik1-133-73042.vs.sakura.ne.jp/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 whether a topic was muted or unmuted was managed by the PATCH /users/me/subscriptions/muted_topics endpoint.

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://ik1-133-73042.vs.sakura.ne.jp/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 = None. Removes the visibility policy previously set for the topic.
  • 1 = Muted. Mutes the topic in a stream.
  • 2 = Unmuted. Unmutes the topic in a muted stream.

In an unmuted stream, a topic visibility policy of unmuted will have the same effect as the "None" visibility policy.

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