Subscribe to a stream
POST https://chat.h2t.iar.kit.edu/api/v1/users/me/subscriptions
Subscribe one or more users to one or more streams.
If any of the specified streams do not exist, they are automatically
created. The initial stream settings will be determined
by the optional parameters, like invite_only, detailed below.
Note that the ability to subscribe oneself and/or other users to a specified
stream depends on the stream's privacy settings.
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.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# Subscribe to the stream "new stream"
result = client.add_subscriptions(
streams=[
{
"name": "new stream",
"description": "New stream for testing",
},
],
)
# To subscribe other users to a stream, you may pass
# the `principals` argument, like so:
user_id = 25
result = client.add_subscriptions(
streams=[
{"name": "new stream", "description": "New stream for testing"},
],
principals=[user_id],
)
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);
// Subscribe to the streams "Verona" and "Denmark"
const meParams = {
subscriptions: JSON.stringify([{name: "Verona"}, {name: "Denmark"}]),
};
console.log(await client.users.me.subscriptions.add(meParams));
// To subscribe another user to a stream, you may pass in
// the `principals` parameter, like so:
const user_id = 7;
const anotherUserParams = {
subscriptions: JSON.stringify([{name: "Verona"}, {name: "Denmark"}]),
principals: JSON.stringify([user_id]),
};
console.log(await client.users.me.subscriptions.add(anotherUserParams));
})();
curl -sSX POST https://chat.h2t.iar.kit.edu/api/v1/users/me/subscriptions \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'subscriptions=[{"description": "Italian city", "name": "Verona"}]'
To subscribe another user to a stream, you may pass in
the principals parameter, like so:
curl -sSX POST https://chat.h2t.iar.kit.edu/api/v1/users/me/subscriptions \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'subscriptions=[{"description": "Italian city", "name": "Verona"}]' \
--data-urlencode 'principals=["ZOE@zulip.com"]'
Parameters
subscriptions (object)[] required
Example: [{"name": "Verona", "description": "Italian city"}]
A list of dictionaries containing the key name and value
specifying the name of the stream to subscribe. If the stream does not
exist a new stream is created. The description of the stream created can
be specified by setting the dictionary key description with an
appropriate value.
subscriptions object details:
-
name: string required The name of the stream.
Clients should use the max_stream_name_length returned by the
POST /register endpoint to determine
the maximum stream name length.
-
description: string optional The description
to use for a new stream being created, in text/markdown format.
Clients should use the max_stream_description_length returned
by the POST /register endpoint to
determine the maximum stream description length.
principals (string)[] | (integer)[] optional
Example: ["ZOE@zulip.com"]
A list of user IDs (preferred) or Zulip API 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).
authorization_errors_fatal boolean optional
Example: false
A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private stream) should be
considered fatal or not. When true, an authorization error is reported
as such. When set to false, the response will be a 200 and any streams
where the request encountered an authorization error will be listed
in the unauthorized key.
Defaults to true.
announce boolean optional
Example: true
If one of the streams specified did not exist previously and is thus created
by this call, this determines whether notification bot
will send an announcement about the new stream's creation.
Defaults to false.
invite_only boolean optional
Example: true
As described above, this endpoint will create a new stream if passed
a stream name that doesn't already exist. This parameters and the ones
that follow are used to request an initial configuration of a created
stream; they are ignored for streams that already exist.
This parameter determines whether any newly created streams will be
private streams.
Defaults to false.
is_web_public boolean optional
Example: true
This parameter determines whether any newly created streams will be
web-public streams.
Note that creating web-public streams requires the
WEB_PUBLIC_STREAMS_ENABLED server setting
to be enabled on the Zulip server in question, the organization
to have enabled the enable_spectator_access realm setting, and
the current use to have permission under the organization's
create_web_public_stream_policy realm setting.
Changes: New in Zulip 5.0 (feature level 98).
Defaults to false.
is_default_stream boolean optional
Example: true
This parameter determines whether any newly created streams will be
added as default streams for new users joining
the organization.
Changes: New in Zulip 8.0 (feature level 200). Previously, default stream status
could only be changed using the dedicated API endpoint.
Defaults to false.
history_public_to_subscribers boolean optional
Example: false
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the shared history
option in documentation.
stream_post_policy integer optional
Example: 2
Policy for which users can post messages to the stream.
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only full members can post.
- 4 = Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
Defaults to 1.
message_retention_days string | integer optional
Example: "20"
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. Two special string format
values are supported:
"realm_default": Return to the organization-level setting."unlimited": Retain messages forever.
Changes: Prior to Zulip 5.0 (feature level 91), retaining
messages forever was encoded using "forever" instead of
"unlimited".
New in Zulip 3.0 (feature level 17).
can_remove_subscribers_group integer optional
Example: 20
ID of the user group whose members are
allowed to unsubscribe others from the stream. Note that a user
who is a member of the specified user group must also have
access to the stream in order to
unsubscribe others.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
"role:internet" and "role:owners".
Changes: Before Zulip 8.0 (feature level 197),
the can_remove_subscribers_group setting
was named can_remove_subscribers_group_id.
New in Zulip 7.0 (feature level 161).
Response
Return values
-
subscribed: object
A dictionary where the key is the Zulip API email address of the user/bot
and the value is a list of the names of the streams that were subscribed
to as a result of the query.
-
already_subscribed: object
A dictionary where the key is the Zulip API email address of the user/bot
and the value is a list of the names of the streams that the user/bot is
already subscribed to.
-
unauthorized: (string)[]
A list of names of streams that the requesting user/bot was not
authorized to subscribe to. Only present if "authorization_errors_fatal": false.
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:
{
"already_subscribed": {
"iago@zulip.com": [
"new stream"
]
},
"msg": "",
"result": "success",
"subscribed": {
"newbie@zulip.com": [
"new stream"
]
}
}
An example JSON response for when the requesting user does not have
access to a private stream and "authorization_errors_fatal": true:
{
"code": "BAD_REQUEST",
"msg": "Unable to access stream (private_stream).",
"result": "error"
}