Add subscriptions
Subscribe one or more users to one or more streams.
POST https://zulip.hopi.cz/api/v1/users/me/subscriptions
If any of the specified streams do not exist, they are automatically
created, and configured using the invite_only setting specified in
the arguments (see below).
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'
}
]
)
print(result)
# To subscribe another user to a stream, you may pass in
# the `principals` argument, like so:
result = client.add_subscriptions(
streams=[
{'name': 'new stream', 'description': 'New stream for testing'}
],
principals=['newbie@zulip.com']
)
print(result)
More examples and documentation can be found here.
const zulip = require('zulip-js');
// Pass the path to your zuliprc file here.
const config = {
zuliprc: 'zuliprc',
};
zulip(config).then((client) => {
// Subscribe to the streams "Verona" and "Denmark"
const meParams = {
subscriptions: JSON.stringify([
{'name': 'Verona'},
{'name': 'Denmark'}
]),
};
client.users.me.subscriptions.add(meParams).then(console.log);
// To subscribe another user to a stream, you may pass in
// the `principals` argument, like so:
const anotherUserParams = {
subscriptions: JSON.stringify([
{'name': 'Verona'},
{'name': 'Denmark'}
]),
principals: JSON.stringify(['ZOE@zulip.org']),
};
client.users.me.subscriptions.add(anotherUserParams).then(console.log);
});
curl https://zulip.hopi.cz/api/v1/users/me/subscriptions \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
-d 'subscriptions=[{"name": "Verona"}]'
To subscribe another user to a stream, you may pass in
the principals argument, like so:
curl https://zulip.hopi.cz/api/v1/users/me/subscriptions \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
-d 'subscriptions=[{"name": "Verona"}]' \
-d 'principals=["ZOE@zulip.com"]'
Arguments
| Argument |
Example |
Required |
Description |
subscriptions |
[{"name":"Verona","description":"Italian City"}] |
Yes |
A list of dictionaries, where each dictionary contains key/value pairs specifying a particular stream to subscribe to. You can specify an initial description here when creating a new stream. Note: This argument is called streams and not subscriptions in our Python API. |
invite_only |
true |
No |
A boolean specifying whether the streams specified in subscriptions are invite-only or not.
Defaults to false. |
announce |
true |
No |
If announce is True and one of the streams specified in subscriptions has to be created (i.e. doesn't exist to begin with), an announcement will be made notifying that a new stream was created. |
principals |
["ZOE@zulip.com"] |
No |
A list of email addresses of the users that will be subscribed to the streams specified in the subscriptions argument. If not provided, then the requesting user/bot is subscribed.
Defaults to []. |
authorization_errors_fatal |
false |
No |
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 returned JSON payload indicates that there was an authorization error, but the response is still considered a successful one.
Defaults to true. |
Response
Return values
-
subscribed: A dictionary where the key is the 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: A dictionary where the key is the 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: A list of names of streams that the requesting user/bot
was not authorized to subscribe to.
Example response
A typical successful JSON response may look like:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {
"iago@zulip.com": [
"new stream"
]
}
}
A typical successful JSON response when the user is already subscribed to
the streams specified:
{
"already_subscribed": {
"newbie@zulip.com": [
"new stream"
]
},
"msg": "",
"result": "success",
"subscribed": {}
}
A typical response for when the requesting user does not have access to
a private stream and authorization_errors_fatal is True:
{
"msg": "Unable to access stream (private_stream).",
"result": "error"
}
A typical response for when the requesting user does not have access to
a private stream and authorization_errors_fatal is False:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": [
"private_stream"
]
}