POST /users/me/subscriptions

Default value: "application/x-www-form-urlencoded"

Whether any other users newly subscribed via this request should be sent a direct message, from Notification Bot, notifying them about their new subscription.

No direct messages are sent for any channels that are created as part of this request, regardless of the value of this parameter.

The server will never send direct messages when the total number of users who were subscribed to channels in this request was more than the value of max_bulk_new_subscription_messages, which is available in the POST /register response.

Changes: Before Zulip 11.0 (feature level 397), new subscribers were always sent a Notification Bot direct message, which was unduly expensive when bulk-subscribing thousands of users to a channel.

Default value: true

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

Organization administrators can unsubscribe others from a channel as though they were in this group without being explicitly listed here.

Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting.

Changes: Prior to Zulip 10.0 (feature level 349), channel administrators could not unsubscribe other users if they were not an organization administrator or part of can_remove_subscribers_group. Realm administrators were not allowed to unsubscribe other users from a private channel if they were not subscribed to that channel.

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).

A group-setting value defining the set of users who have permission to delete the messages that they have sent in the channel.

Note that a user must have content access to a channel in order to delete their own message in the channel.

Users with permission to delete any message in the channel and users present in the organization-level can_delete_own_message_group setting can always delete their own messages in the channel if they have content access to that channel.

Changes: New in Zulip 11.0 (feature level 407). Prior to this change, only the users in the organization-level can_delete_any_message_group and can_delete_own_message_group settings were able delete their own messages in the organization.

A group-setting value defining the set of users who have permission to resolve topics in the channel.

Users who have similar realm-level permissions can resolve topics in a channel regardless of the value of this setting.

Changes: New in Zulip 11.0 (feature level 402).

This parameter determines whether any newly created channels will be added as default channels for new users joining the organization.

Changes: New in Zulip 8.0 (feature level 200). Previously, default channel status could only be changed using the dedicated API endpoint.

Default value: false

A group-setting value defining the set of users who have permission to create a new topic in this channel.

Note that using this permission requires also having permission to send messages in the channel.

Note that this must be the role:everyone system group for private channels with protected history.

Changes: New in Zulip 12.0 (feature level 441). Previously, if you could send messages in a channel, you could create topics in the channel.

Number of days that messages sent to this channel 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.
• "unlimited": Retain messages forever.

Changes: Prior to Zulip 5.0 (feature level 91), retaining messages forever was encoded using "forever" instead of "unlimited".

New in Zulip 3.0 (feature level 17).

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

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

Default value: false

Whether named topics and the empty topic (i.e., "general chat" topic) are enabled in this channel.

• "inherit": Messages can be sent to named topics in this channel, and the organization-level realm_topics_policy is used for whether messages can be sent to the empty topic in this channel.
• "allow_empty_topic": Messages can be sent to both named topics and the empty topic in this channel.
• "disable_empty_topic": Messages can be sent to named topics in this channel, but the empty topic is disabled.
• "empty_topic_only": Messages can be sent to the empty topic in this channel, but named topics are disabled. See "general chat" channels.

The "empty_topic_only" policy can only be set if all existing messages in the channel are already in the empty topic.

When creating a new channel, if the topics_policy is not specified, the "inherit" option will be set.

Changes: In Zulip 11.0 (feature level 404), the "empty_topic_only" option was added.

New in Zulip 11.0 (feature level 392).

Valid values:

• "empty_topic_only"
• "inherit"
• "allow_empty_topic"
• "disable_empty_topic"

This parameter adds the newly created channel to the specified channel folder.

Changes: New in Zulip 11.0 (feature level 389).

This parameter determines whether any newly created channels will be web-public channels.

Note that creating web-public channels requires the WEB_PUBLIC_STREAMS_ENABLED server setting to be enabled on the Zulip server in question, the organization to have enabled the enable_spectator_access realm setting, and the current use to have permission under the organization's can_create_web_public_channel_group realm setting.

Changes: New in Zulip 5.0 (feature level 98).

Default value: false

A list of user IDs (preferred) or Zulip API email addresses of the users to be subscribed to or unsubscribed from the channels specified in the subscriptions parameter.

If not provided, then the requesting user/bot will be subscribed/unsubscribed from the specified channels.

Changes: Before Zulip 3.0 (feature level 9), only the Zulip API email address string format was supported.

A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private channel) 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 channels where the request encountered an authorization error will be listed in the unauthorized key.

Default value: true

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

Organization administrators can administer every channel as though they were in this group without being explicitly listed here.

Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting.

Changes: Prior to Zulip 10.0 (feature level 349) a user needed to have content access to a channel in order to modify it. The exception to this rule was that organization administrators can edit channel names and descriptions without having full access to the channel.

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

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

Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting.

Note that using this permission to send a message to a new topic requires also having permission to create new topics in the channel.

Changes: New in Zulip 10.0 (feature level 333). Previously stream_post_policy field used to control the permission to post in the channel.

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

Default value: false

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

Everyone, excluding guests, can subscribe to any public channel irrespective of this setting.

Users in this group can subscribe to a private channel as well.

Note that a user must have content access to a channel and permission to administer the channel in order to modify this setting.

Changes: New in Zulip 10.0 (feature level 357).

A group-setting value defining the set of users who have permission to delete any message in the channel.

Note that a user must have content access to a channel in order to delete any message in the channel.

Users present in the organization-level can_delete_any_message_group setting can always delete any message in the channel if they have content access to that channel.

Changes: New in Zulip 11.0 (feature level 407). Prior to this change, only the users in can_delete_any_message_group were able delete any message in the organization.

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

Corresponds to the shared history option for private channels.

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

Note that a user must have content access to a channel in order to move messages out of the channel.

Channel administrators and users present in the organization-level can_move_messages_between_channels_group setting can always move messages out of the channel if they have content access to the channel.

Changes: New in Zulip 11.0 (feature level 396). Prior to this change, only the users in can_move_messages_between_channels_group were able move messages between channels.

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

Note that a user must have content access to a channel in order to move messages within the channel.

Channel administrators and users present in the organization-level can_move_messages_between_topics_group setting can always move messages within the channel if they have content access to the channel.

Changes: New in Zulip 11.0 (feature level 396). Prior to this change, only the users in can_move_messages_between_topics_group were able move messages between topics of a channel.

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

Users who can administer the channel or have similar realm-level permissions can add subscribers to a public channel regardless of the value of this setting.

Users in this group need not be subscribed to a private channel to add subscribers to it.

Note that a user must have content access to a channel and permission to administer the channel in order to modify this setting.

Changes: New in Zulip 10.0 (feature level 342). Previously, there was no channel-level setting for this permission.

A list of dictionaries containing the key name and value specifying the name of the channel to subscribe. If the channel does not exist a new channel is created. The description of the channel created can be specified by setting the dictionary key description with an appropriate value.

The name of the channel.

Clients should use the max_stream_name_length returned by the POST /register endpoint to determine the maximum channel name length.

The description to use for a new channel being created, in text/markdown format.

See the help center article on message formatting for details on Zulip-flavored Markdown.

Clients should use the max_stream_description_length returned by the POST /register endpoint to determine the maximum channel description length.