Add subscriptions

Subscribe one or more users to one or more streams.

POST https://chat.virginvoyages.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

#!/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 -X POST https://chat.virginvoyages.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 -X POST https://chat.virginvoyages.com/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.

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.

history_public_to_subscribers false No

A boolean indicating if the history should be available to newly subscribed members. Defaults to "None".

is_announcement_only false No

A boolean indicating if the stream is an announcements only stream. Only organization admins can post to announcements only streams. 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.

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