Subscribe to a stream

Subscribe one or more users to one or more streams.

POST https://openpl.zulipchat.com/api/v1/users/me/subscriptions

If any of the specified streams do not exist, they are automatically created. The initial stream settings will be determined by the optional parameters like invite_only detailed 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',
        },
    ],
)
# To subscribe other users to a stream, you may pass
# the `principals` argument, like so:
user_id = 25
result = client.add_subscriptions(
    streams=[
        {'name': 'new stream', 'description': 'New stream for testing'},
    ],
    principals=[user_id],
)
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(async (client) => {
    // Subscribe to the streams "Verona" and "Denmark"
    const meParams = {
        subscriptions: JSON.stringify([{name: "Verona"}, {name: "Denmark"}]),
    };
    return await client.users.me.subscriptions.add(meParams);
}).then(console.log).catch(console.err);

Zulip(config).then(async (client) => {
    // To subscribe another user to a stream, you may pass in
    // the `principals` parameter, like so:
    const user_id = 7;
    const anotherUserParams = {
        subscriptions: JSON.stringify([{name: "Verona"}, {name: "Denmark"}]),
        principals: JSON.stringify([user_id]),
    };
    return await client.users.me.subscriptions.add(anotherUserParams);
}).then(console.log).catch(console.err);

curl -sSX POST https://openpl.zulipchat.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 parameter, like so:

curl -sSX POST https://openpl.zulipchat.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"]'

Parameters

subscriptions required

Example: [{"name": "Verona", "description": "Italian city"}]

A list of dictionaries containing 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.


principals optional

Example: ["ZOE@zulip.com"]

A list of user ids (preferred) or Zulip display email addresses of the users to be subscribed to or unsubscribed from the streams specified in the subscriptions parameter. If not provided, then the requesting user/bot is subscribed.

Changes: The integer format is new in Zulip 3.0 (feature level 9).


authorization_errors_fatal optional

Example: False

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 response will be a 200 and any streams where the request encountered an authorization error will be listed in the unauthorized key.

Defaults to true.


announce optional

Example: True

If one of the streams specified did not exist previously and is thus craeted by this call, this determines whether notification bot will send an announcement about the new stream's creation.

Defaults to false.


invite_only optional

Example: True

As described above, this endpoint will create a new stream if passed a stream name that doesn't already exist. This parameters and the ones that follow are used to request an initial configuration of a created stream; they are ignored for streams that already exist.

This parameter determines whether any newly created streams will be private streams.

Defaults to false.


history_public_to_subscribers optional

Example: False

Whether the stream's message history should be available to newly subscribed members, or users can only access messages they actually received while subscribed to the stream.

Corresponds to the shared history option in documentation.


stream_post_policy optional

Example: 2

Policy for which users can post messages to the stream.

  • 1 => Any user can post.
  • 2 => Only administrators can post.
  • 3 => Only new members can post.

Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

Defaults to 1.


message_retention_days optional

Example: 20

Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. Two special string format values are supported:

  • "realm_default" => Return to the organization-level setting.
  • "forever" => Retain messages forever.

Changes: New in Zulip 3.0 (feature level 17).


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.

    • {email_address}: 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.

    • {email_address}`: List of the names of the streams that the user is already subscribed to.
  • unauthorized: A list of names of streams that the requesting user/bot was not authorized to subscribe to. Only present if authorization_errors_fatal=false.

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