Add subscriptions

Subscribe one or more users to one or more streams.

POST https://wikimedia.zulipchat.com/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

curl https://wikimedia.zulipchat.com/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://wikimedia.zulipchat.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'subscriptions=[{"name": "Verona"}]' \
    -d 'principals=["ZOE@zulip.com"]'
#!/usr/bin/env python3

import zulip

# Download ~/zuliprc-dev from your dev server
client = zulip.Client(config_file="~/zuliprc-dev")

# 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');

// Download zuliprc-dev from your dev server
const config = {
    zuliprc: 'zuliprc-dev',
};

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);
});

Arguments

Argument Example Required Description
subscriptions [{'name': 'Verona'}] Yes

A list of dictionaries, where each dictionary contains key/value pairs specifying a particular stream to subscribe to. 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.

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.

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.

Response

Return values

  • subscribed
  • already_subscribed
  • unauthorized

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"
    ]
}