Unsubscribe from a channel
DELETE https://chat.xnoc.net/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.
When other users are removed from a channel, they may receive
a direct message notifying them that they were unsubscribed by
the current user; see
send_messages_to_removed_subscribers
below.
Changes: Prior to Zulip 13.0 (feature level 515), the
server never sent direct messages to users who were unsubscribed
from one or more channels by the current user.
Before Zulip 10.0 (feature level 362), subscriptions in archived
channels could not be modified.
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)
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 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));
})();
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Zulip users and bots.
Note: Unsubscribing another user from a channel requires
administrative privileges.
curl -sSX DELETE https://chat.xnoc.net/api/v1/users/me/subscriptions \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode 'subscriptions=["Verona", "Denmark"]'
You may specify the principals parameter like so:
curl -sSX DELETE https://chat.xnoc.net/api/v1/users/me/subscriptions \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode 'subscriptions=["Verona", "Denmark"]' \
--data-urlencode 'principals=[11]' \
--data-urlencode send_messages_to_removed_subscribers=true
Parameters
subscriptions (string)[] required
Example: ["Verona", "Denmark"]
A list of channel names to unsubscribe from. This parameter is called
streams in our Python API.
principals (string)[] | (integer)[] optional
Example: [11]
A list of user IDs (preferred) or Zulip API email
addresses of the users to be subscribed to or unsubscribed
from the channels specified in the subscriptions parameter.
If not provided, then the requesting user/bot will be
subscribed/unsubscribed from the specified channels.
Changes: Before Zulip 3.0 (feature level 9), only the
Zulip API email address string format was supported.
send_messages_to_removed_subscribers boolean optional
Example: true
Whether other users unsubscribed via this request should be sent a
direct message, from Notification Bot, notifying them that they
were unsubscribed and by whom.
The server will never send direct messages when the total number of
users who were unsubscribed from channels in this request was more
than the value of max_bulk_subscription_messages, which is
available in the POST /register response.
Changes: New in Zulip 13.0 (feature level 515).
Defaults to true.
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.
-
messages_sent_to_removed_subscribers: boolean
Only present if the parameter send_messages_to_removed_subscribers
in the request was true.
Whether Notification Bot DMs were in fact sent to the removed
subscribers as requested by the
send_messages_to_removed_subscribers parameter. Clients may
find this value useful to communicate with users about the
effect of this request.
Changes: New in Zulip 13.0 (feature level 515).
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:
{
"messages_sent_to_removed_subscribers": true,
"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"
}