Add subscriptions

Subscribe one or more users to one or more streams.

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

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 -sSX POST https://chat.zymocosm.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode subscriptions='[{"description": "Italian City", "name": "Verona"}]'

To subscribe another user to a stream, you may pass in the principals argument, like so:

curl -sSX POST https://chat.zymocosm.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode subscriptions='[{"description": "Italian City", "name": "Verona"}]' \
    --data-urlencode principals='["ZOE@zulip.com"]'

Arguments

Argument	Example	Required	Description
`subscriptions`	`[{"name":"Verona","description":"Italian City"}]`	Yes	A list of dictionaries containing the the key `name` and value specifying the name of the stream to subscribe. If the stream does not exist a new stream is created. The description of the stream created can be specified by setting the dictionary key `description` with an appropriate value. 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"
    ]
}

Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events