Get subscribed streams

Get all streams that the user is subscribed to.

GET https://envied-rb.zulipchat.com/api/v1/users/me/subscriptions

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Get all streams that the user is subscribed to
result = client.get_subscriptions()
print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Get all streams that the user is subscribed to
    console.log(await client.streams.subscriptions.retrieve());
})();

curl -sSX GET -G https://envied-rb.zulipchat.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

You may pass the include_subscribers query parameter as follows:

curl -sSX GET -G https://envied-rb.zulipchat.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode include_subscribers=true

Parameters

include_subscribers boolean optional

Example: true

Whether each returned stream object should include a subscribers field containing a list of the user IDs of its subscribers.

(This may be significantly slower in organizations with thousands of users subscribed to many streams.)

Changes: New in Zulip 2.1.0.

Defaults to false.


Response

Return values

  • subscriptions: (object)[] A list of dictionaries where each dictionary contains information about one of the subscribed streams.

    • stream_id: integer The unique ID of a stream.

    • name: string The name of a stream.

    • description: string The short description of a stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • rendered_description: string A short description of a stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • date_created: integer The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • subscribers: (integer)[] A list of user IDs of users who are also subscribed to a given stream. Included only if include_subscribers is true.

    • desktop_notifications: boolean A boolean specifying whether desktop notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this stream.

    • email_notifications: boolean A boolean specifying whether email notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this stream.

    • wildcard_mentions_notify: boolean A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this stream.

      A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this stream.

    • push_notifications: boolean A boolean specifying whether push notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this stream.

    • audible_notifications: boolean A boolean specifying whether audible notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this stream.

    • pin_to_top: boolean A boolean specifying whether the given stream has been pinned to the top.

    • email_address: string Email address of the given stream, used for sending emails to the stream.

    • is_muted: boolean Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in All messages view (previously known as Home view).

      Changes: Prior to Zulip 2.1, this feature was represented by the more confusingly named in_home_view (with the opposite value, in_home_view=!is_muted).

    • in_home_view: boolean Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: boolean Whether only organization administrators can post to the stream.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

    • is_web_public: boolean Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • role: integer The user's role within the stream (distinct from the user's organization-level role). Valid values are:

      • 20 => Stream administrator.
      • 50 => Subscriber.

      Changes: New in Zulip 4.0 (feature level 31).

    • color: string The user's personal color for the stream.

    • stream_post_policy: integer Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

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

    • message_retention_days: integer Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

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

    • history_public_to_subscribers: boolean Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • stream_weekly_traffic: integer The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "subscriptions": [
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "description": "A Scandinavian country",
            "desktop_notifications": true,
            "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981",
            "invite_only": false,
            "is_muted": false,
            "name": "Denmark",
            "pin_to_top": false,
            "push_notifications": false,
            "role": 20,
            "stream_id": 1,
            "subscribers": [
                7,
                10,
                11,
                12,
                14
            ]
        },
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "description": "Located in the United Kingdom",
            "desktop_notifications": true,
            "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981",
            "invite_only": false,
            "is_muted": false,
            "name": "Scotland",
            "pin_to_top": false,
            "push_notifications": false,
            "role": 50,
            "stream_id": 3,
            "subscribers": [
                7,
                11,
                12,
                14
            ]
        }
    ]
}