Add subscriptions

Subscribe one or more users to one or more streams.

POST https://zulip.sagemath.org/api/v1/users/me/subcriptions

Usage examples

curl https://zulip.sagemath.org/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.sagemath.org/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'subscriptions=[{"name": "Verona"}]' \
    -d 'principals=["[email protected]"]'
#!/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=['[email protected]']
)
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(['[email protected]']),
    };
    client.users.me.subscriptions.add(anotherUserParams).then(console.log);
});

Arguments

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

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` or `False` Optional

A boolean specifying whether the streams specified in subscriptions are invite-only or not. Default is False.

announce `True` or `False` Optional

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 ['[email protected]'] Optional

A list of email addresses of the users that will be subscribed to the streams specified in the subscriptions argument. Default is []. If not provided, then the requesting user/bot is subscribed.

authorization_errors_fatal `True` or `False` Optional

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. Default is True, in which case 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: 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": {
        "[email protected]": [
            "new stream"
        ]
    }
}

A typical successful JSON response when the user is already subscribed to the streams specified:

{
    "already_subscribed": {
        "[email protected]": [
            "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"
    ]
}