Unsubscribe from a stream

DELETE https://zulip.engr.uconn.edu/api/v1/users/me/subscriptions

Unsubscribe yourself or other users from one or more streams.

In addition to managing the current user's subscriptions, this endpoint can be used by organization administrators to remove other users from streams, or to remove a bot that the current user is the bot_owner for from any stream that the current user can access.

Changes: Before Zulip 6.0 (feature level 145), only organization administrators could remove other users from streams.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Unsubscribe from the stream "new stream"
result = client.remove_subscriptions(
    ["new stream"],
)
# Unsubscribe another user from the stream "new stream"
result = client.remove_subscriptions(
    ["new stream"],
    principals=["newbie@zulip.com"],
)
print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Unsubscribe from the stream "Denmark"
    const meParams = {
        subscriptions: JSON.stringify(["Denmark"]),
    };
    console.log(await client.users.me.subscriptions.remove(meParams));

    const user_id = 7;
    // Unsubscribe Zoe from the stream "Denmark"
    const zoeParams = {
        subscriptions: JSON.stringify(["Denmark"]),
        principals: JSON.stringify([user_id]),
    };
    console.log(await client.users.me.subscriptions.remove(zoeParams));
})();

Note: Unsubscribing another user from a stream requires administrative privileges.

curl -sSX DELETE https://zulip.engr.uconn.edu/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'subscriptions=["Verona", "Denmark"]'

You may specify the principals parameter like so:

curl -sSX DELETE https://zulip.engr.uconn.edu/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'subscriptions=["Verona", "Denmark"]' \
    --data-urlencode 'principals=["ZOE@zulip.com"]'

Parameters

subscriptions (string)[] required

Example: ["Verona", "Denmark"]

A list of stream names to unsubscribe from. This parameter is called streams in our Python API.


principals (string)[] | (integer)[] optional

Example: ["ZOE@zulip.com"]

A list of user ids (preferred) or Zulip display email addresses of the users to be subscribed to or unsubscribed from the streams specified in the subscriptions parameter. If not provided, then the requesting user/bot is subscribed.

Changes: The integer format is new in Zulip 3.0 (feature level 9).


Response

Return values

  • not_removed: (string)[]

    A list of the names of streams that the user is already unsubscribed from, and hence doesn't need to be unsubscribed.

  • removed: (string)[]

    A list of the names of streams which were unsubscribed from as a result of the query.

Example response(s)

A typical successful JSON response may look like:

{
    "msg": "",
    "not_removed": [],
    "removed": [
        "new stream"
    ],
    "result": "success"
}

A typical failed JSON response for when the target stream does not exist:

{
    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Stream 'nonexistent_stream' does not exist",
    "result": "error",
    "stream": "nonexistent_stream"
}