Create a channel
POST https://chat.zulip.org/api/v1/channels/create
Create a new channel and optionally
subscribe users to the newly created channel. The initial channel settings
will be determined by the optional parameters, like invite_only, detailed below.
Changes: New in Zulip 11.0 (feature level 417). Previously, this was only possible via
the POST /api/subscribe endpoint, which handled both creation and subscription.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
request = {
"name": "music_group",
"description": "Channel for discussing and learning about music.",
"subscribers": [],
}
result = client.call_endpoint(url="channels/create", method="POST", request=request)
print(result)
curl -sSX POST https://chat.zulip.org/api/v1/channels/create \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode name=music \
--data-urlencode 'subscribers=[16, 12]'
Parameters
name string required
Example: "music"
The name of the new channel.
Clients should use the max_stream_name_length returned by the
POST /register endpoint to determine
the maximum channel name length.
description string optional
Example: "Channel for discussing all things music!"
The description
to use for the new channel being created, 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.
subscribers (string)[] | (integer)[] required
Example: [16, 12]
A list of user IDs (preferred) or Zulip API email
addresses of the users to be subscribed to the new channel specified in the channel parameter.
announce boolean optional
Example: true
This determines whether notification bot
will send an announcement about the new channel's creation.
Defaults to false.
invite_only boolean optional
Example: true
This parameter and the ones
that follow are used to request an initial configuration of the new channel.
This parameter determines whether the newly created channel will be
a private channel.
Defaults to false.
is_web_public boolean optional
Example: true
This parameter determines whether the newly created channel will be
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 user to have permission under the organization's
can_create_web_public_channel_group realm setting.
Defaults to false.
is_default_stream boolean optional
Example: true
This parameter determines whether the newly created channel will be
added as a default channel for new users joining
the organization.
Defaults to false.
folder_id integer | null optional
Example: null
The ID of the folder to which the channel belongs.
Is null if channel does not belong to any folder.
Changes: New in Zulip 11.0 (feature level 389).
send_new_subscription_messages boolean optional
Example: true
Whether any other users newly subscribed via this request should be
sent a Notification Bot DM notifying them about their new
subscription.
The server will never send Notification Bot DMs if more than
max_bulk_new_subscription_messages (available in the POST
/register response) users were subscribed in
this request.
Changes: Before Zulip 11.0 (feature level 397), new subscribers
were always sent a Notification Bot DM, which was unduly expensive
when bulk-subscribing thousands of users to a channel.
Defaults to true.
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".
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.
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_add_subscribers_group integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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).
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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.
Changes: New in Zulip 10.0 (feature level 333). Previously
stream_post_policy field used to control the permission to
post in the channel.
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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).
This parameter must be one of the following:
The ID of the user group with this permission.
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 integer | object optional
Example: null
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 must be one of the following:
The ID of the user group with this permission.
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
Return values
Example response(s)
Success response for creating a channel.
{
"id": 50,
"msg": "",
"result": "success"
}
Bad request as channel already exists.
{
"code": "CHANNEL_ALREADY_EXISTS",
"msg": "Channel 'discussions' already exists",
"result": "error"
}