Update personal preferences for a topic

POST https://recurse.zulipchat.com/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://recurse.zulipchat.com/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.

Clients should use the max_topic_length returned by the POST /register endpoint to determine the maximum topic length.


visibility_policy integer required

Example: 1

Controls which visibility policy to set.

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

Changes: In Zulip 7.0 (feature level 219), added followed as a visibility policy option.

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