Update a channel
PATCH https://kent.zulip.conventionofstates.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://kent.zulip.conventionofstates.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
create_web_public_stream_policy 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 integer optional
Example: 20
ID of the user group whose members are
allowed to unsubscribe others from the 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.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
"role:internet" and "role:owners".
Changes: 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).
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"
}