Update a channel

PATCH https://shipyard.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:

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

Usage examples

#!/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,
    "stream_post_policy": 2,
    "is_private": True,
}
result = client.update_stream(request)
print(result)

curl -sSX PATCH https://shipyard.zulipchat.com/api/v1/streams/1 \
    -u BOT_EMAIL_ADDRESS:BOT_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 text/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 in documentation.

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

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.


stream_post_policy integer optional

Example: 2

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.

Defaults to 1.


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


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][update-group-setting].

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

can_remove_subscribers_group object details:

  • new: integer | object required

    The new group-setting value for who would have the permission to remove subscribers from the channel.

    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 the permission to remove subscribers from the channel.

    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][update-group-setting].

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.

can_administer_channel_group object details:

  • new: integer | object required

    The new group-setting value for who would have the permission to administer this channel.

    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 the permission to administer this channel.

    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.


is_announcement_only boolean optional Deprecated

Example: true

Whether the channel is limited to announcements.

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


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