Update a channel

PATCH https://your-org.zulipchat.com/api/v1/streams/{stream_id}

Configure the channel with the ID stream_id. This endpoint supports an organization administrator editing any property of a channel, including:

Channel name and description
Channel permissions, including privacy and who can send.

Note that an organization administrator's ability to change a private channel's permissions depends on them being subscribed to the channel.

Changes: Before Zulip 10.0 (feature level 362), channel privacy could not be edited for archived channels.

Removed stream_post_policy and is_announcement_only parameters in Zulip 10.0 (feature level 333), as permission to post in the channel is now controlled by can_send_message_group.

Usage examples

Python
curl

#!/usr/bin/env python3

import zulip

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

# Update settings for the channel with a given ID.
request = {
    "stream_id": stream_id,
    "is_private": True,
}
result = client.update_stream(request)
print(result)

The -u line implements HTTP Basic authentication. See the Authorization header documentation for how to get those credentials for Zulip users and bots.

curl -sSX PATCH https://your-org.zulipchat.com/api/v1/streams/1 \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode 'description=Discuss Italian history and travel destinations.' \
    --data-urlencode new_name=Italy \
    --data-urlencode is_private=true

Parameters

stream_id integer required in path

Example: 1

The ID of the channel to access.

description string optional

Example: "Discuss Italian history and travel destinations."

The new description for the channel, in Zulip-flavored Markdown format.

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

Changes: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64).

new_name string optional

Example: "Italy"

The new name for the channel.

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

Changes: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64).

is_private boolean optional

Example: true

Change whether the channel is a private channel.

is_web_public boolean optional

Example: true

Change whether the channel is a web-public channel.

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

history_public_to_subscribers boolean optional

Example: false

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.

It's an error for this parameter to be false for a public or web-public channel and when is_private is false.

This can only be false if can_create_topic_group for the channel is the role:everyone system group.

Changes: Before Zulip 6.0 (feature level 136), history_public_to_subscribers was silently ignored unless the request also contained either is_private or is_web_public.

is_default_stream boolean optional

Example: false

Add or remove the channel as a default channel 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.

message_retention_days string | integer optional

Example: "20"

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

is_archived boolean optional

Example: true

A boolean indicating whether the channel is archived or unarchived. Currently only allows unarchiving previously archived channels.

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

folder_id integer | null optional

Example: 1

ID of the new channel folder to which the channel should belong.

A null value indicates the user wants to remove the channel from its current channel folder.

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

topics_policy string optional

Example: "inherit"

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

Must be one of: "inherit", "allow_empty_topic", "disable_empty_topic", "empty_topic_only".

can_add_subscribers_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to add subscribers to this channel expressed as an update to a group-setting value.

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.

can_add_subscribers_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_remove_subscribers_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to unsubscribe others from this channel expressed as an update to a group-setting value.

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 7.0 (feature level 161).

can_remove_subscribers_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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 object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to administer this channel expressed as an update to a group-setting value.

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

Note that a user must have content access to a channel in order to add other subscribers to the channel.

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.

can_administer_channel_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_delete_any_message_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to delete any message in the channel expressed as an update to a group-setting value.

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.

can_delete_any_message_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_delete_own_message_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to delete the messages that they have sent in the channel expressed as an update to a group-setting value.

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.

can_delete_own_message_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_move_messages_out_of_channel_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to move messages out of this channel expressed as an update to a group-setting value.

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.

can_move_messages_out_of_channel_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_move_messages_within_channel_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to move messages within this channel expressed as an update to a group-setting value.

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.

can_move_messages_within_channel_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_send_message_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to post in this channel expressed as an update to a group-setting value.

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.

can_send_message_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_subscribe_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to subscribe themselves to this channel expressed as an update to a group-setting value.

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

can_subscribe_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_resolve_topics_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to to resolve topics in this channel expressed as an update to a group-setting value.

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

can_resolve_topics_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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_create_topic_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}

The set of users who have permission to create new topics in this channel expressed as an update to a group-setting value.

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

For private channels with protected history, this setting can only be set to role:everyone system group.

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.

can_create_topic_group object details:

new: integer | object required
The new group-setting value for who would have this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.
old: integer | object optional
The expected current group-setting value for who has this permission.
This parameter must be one of the following:
1. The ID of the user group with this permission.
2. An object with the following 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.

Response

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

An example JSON response for when the supplied channel does not exist:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid channel ID",
    "result": "error"
}

An example JSON response for when invalid combination of channel permission parameters are passed:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid parameters",
    "result": "error"
}

An example JSON response for when trying to set moderation request channel to be public:

{
    "code": "BAD_REQUEST",
    "msg": "A moderation request channel cannot be public.",
    "result": "error"
}

API documentation home

Messages

Scheduled messages

Message reminders

Drafts

Navigation views

Channels

Users

Invitations

Server & organizations

Real-time events

Interactive bots

Specialty endpoints

Back to Zulip

Update a channel

Usage examples

Parameters

Response

Example response(s)