Unsubscribe from a channel

DELETE https://gizmo.zulipchat.com/api/v1/users/me/subscriptions

Unsubscribe yourself or other users from one or more channels.

In addition to managing the current user's subscriptions, this endpoint can be used to remove other users from channels. This is possible in 3 situations:

• Organization administrators can remove any user from any channel.
• Users can remove a bot that they own from any channel that the user can access.
• Users can unsubscribe any user from a channel if they have access to the channel and are a member of the user group specified by the can_remove_subscribers_group for the channel.

Changes: Before Zulip 8.0 (feature level 208), if a user specified by the principals parameter was a deactivated user, or did not exist, then an HTTP status code of 403 was returned with code: "UNAUTHORIZED_PRINCIPAL" in the error response. As of this feature level, an HTTP status code of 400 is returned with code: "BAD_REQUEST" in the error response for these cases.

Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

Before Zulip 7.0 (feature level 161), the can_remove_subscribers_group_id for all channels was always the system group for organization administrators.

Before Zulip 6.0 (feature level 145), users had no special privileges for managing bots that they own.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Unsubscribe from channel "python-test".
result = client.remove_subscriptions(
    ["python-test"],
)
# Unsubscribe another user from channel "python-test".
result = client.remove_subscriptions(
    ["python-test"],
    principals=["newbie@zulip.com"],
)
print(result)

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 channel "Denmark"
    const meParams = {
        subscriptions: JSON.stringify(["Denmark"]),
    };
    console.log(await client.users.me.subscriptions.remove(meParams));

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

curl -sSX DELETE https://gizmo.zulipchat.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'subscriptions=["Verona", "Denmark"]'

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

Parameters

Response

Return values

• not_removed: (string)[]

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

• removed: (string)[]

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

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": "",
    "not_removed": [],
    "removed": [
        "testing-help"
    ],
    "result": "success"
}

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

{
    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Channel 'nonexistent' does not exist",
    "result": "error",
    "stream": "nonexistent"
}