Get subscribed channels

GET https://chat.zulip.org/api/v1/users/me/subscriptions

Get all channels that the user is subscribed to.

Usage examples

#!/usr/bin/env python3

import zulip

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

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

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 channels that the user is subscribed to
    console.log(await client.streams.subscriptions.retrieve());
})();

curl -sSX GET -G https://chat.zulip.org/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

curl -sSX GET -G https://chat.zulip.org/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode include_subscribers=true

Parameters

Response

Return values

• subscriptions: (object)[]

  A list of dictionaries where each dictionary contains information about one of the subscribed channels.

  Changes: Removed email_address field from the dictionary in Zulip 8.0 (feature level 226).

  Removed role field from the dictionary in Zulip 6.0 (feature level 133).

  • stream_id: integer

    The unique ID of a channel.

  • name: string

    The name of a channel.

  • description: string

    The description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.

    See also rendered_description.

  • rendered_description: string

    The description of the channel rendered as HTML, intended to be used when displaying the channel 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.

    See also description.

  • date_created: integer

    The UNIX timestamp for when the channel was created, in UTC seconds.

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

    Specifies whether the channel is private or not. Only people who have been invited can access a private channel.

  • subscribers: (integer)[]

    A list of user IDs of users who are also subscribed to a given channel. Included only if include_subscribers is true.

  • desktop_notifications: boolean | null

    A boolean specifying whether desktop notifications are enabled for the given channel.

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

  • email_notifications: boolean | null

    A boolean specifying whether email notifications are enabled for the given channel.

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

  • wildcard_mentions_notify: boolean | null

    A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this channel.

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

  • push_notifications: boolean | null

    A boolean specifying whether push notifications are enabled for the given channel.

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

  • audible_notifications: boolean | null

    A boolean specifying whether audible notifications are enabled for the given channel.

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

  • pin_to_top: boolean

    A boolean specifying whether the given channel has been pinned to the top.

  • is_muted: boolean

    Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the Combined feed view (previously known as All messages).

    Changes: Prior to Zulip 2.1.0, 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 channel is muted, with inverted meaning.

    Changes: Deprecated in Zulip 2.1.0. Clients should use is_muted where available.

  • is_announcement_only: boolean

    Whether only organization administrators can post to the channel.

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

  • is_web_public: boolean

    Whether the channel has been configured to allow unauthenticated access to its message history from the web.

  • color: string

    The user's personal color for the channel.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

    Whether the history of the channel is public to its subscribers.

    Currently always true for public channels (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 | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

  • is_recently_active: boolean

    Whether the channel has recent message activity. Clients should use this to implement sorting inactive channels to the bottom.

    Changes: New in Zulip 10.0 (feature level 323). Previously, clients implemented the demote_inactive_streams from local message history, resulting in a choppy loading experience.

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, the channel was recently created and there is insufficient data to estimate the average traffic.

  • can_remove_subscribers_group: integer | object

    A group-setting value defining the set of users who have permission to remove subscribers from this channel.

    Administrators can always unsubscribe others from a channel.

    Note that a user who is a member of the specified user group must also have access to the channel in order to unsubscribe others.

    Changes: Prior to Zulip 10.0 (feature level 320), this value was always the integer ID of a system group.

    Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • can_administer_channel_group: integer | object

    A group-setting value defining the set of users who have permission to administer this channel.

    Note that a user who is a member of the specified user group must also have access to the channel in order to administer the channel.

    Realm admins are allowed to administer a channel they have access to regardless of whether they are present in this group.

    Users in this group can edit channel name and description without subscribing to the channel, but they need to be subscribed to edit channel permissions and add users.

    Changes: New in Zulip 10.0 (feature level 325). Prior to this change, the permission to administer channels was limited to realm administrators.

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, subscriptions only included active channels. Note that some endpoints will never return archived channels unless the client declares explicit support for them via the archived_channels client capability.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "subscriptions": [
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "creator_id": null,
            "description": "A Scandinavian country",
            "desktop_notifications": true,
            "invite_only": false,
            "is_archived": false,
            "is_muted": false,
            "name": "Denmark",
            "pin_to_top": false,
            "push_notifications": false,
            "stream_id": 1,
            "subscribers": [
                7,
                10,
                11,
                12,
                14
            ]
        },
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "creator_id": 8,
            "description": "Located in the United Kingdom",
            "desktop_notifications": true,
            "invite_only": false,
            "is_archived": false,
            "is_muted": false,
            "name": "Scotland",
            "pin_to_top": false,
            "push_notifications": false,
            "stream_id": 3,
            "subscribers": [
                7,
                11,
                12,
                14
            ]
        }
    ]
}