Add subscriptions

Subscribe one or more users to one or more streams.

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

Python
JavaScript
curl

#!/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://chat.convergenceservices.in/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://chat.convergenceservices.in/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"
    ]
}

Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events