Creates a new group channel.
Note: See this page to learn more about channel types.
The following table lists the properties of an HTTP request that this action supports.
Note: If you are creating a 1-on-1 direct messaging channel, it is recommended that you set the value of
is_distinct
to true. Ifis_distinct
is set to true, no new channel is created for a group of users with shared chat history, and every 1-on-1 conversation between the same two users will continue in the existing channel. However, ifis_distinct
is set to false, a new channel is created even for a group of users with shared chat history and previous conversations between these users will not carry over to the new channel.
Properties
Required | Type | Description |
---|---|---|
users[] | array of strings | Specifies an array of one or more IDs of users to invite to the channel, which can be used interchangeably with |
Optional | Type | Description |
---|---|---|
user_ids[] | array of strings | Specifies an array of one or more IDs of users to invite to the channel, which can be used interchangeably with |
name | string | Specifies the name of the channel, or the channel topic. The length is limited to 191 characters. (Default: group channel) |
channel_url | string | Specifies the URL of the channel. Only numbers, characters, and underscores are allowed. The length is 4 to 100 characters, inclusive. If not specified, a URL is automatically generated. |
cover_url | string | Specifies the URL of the channel's cover image. The length is limited to 2,048 characters. |
cover_file | file | Uploads an image file of your choice to be used as the channel's cover image. |
custom_type | string | Specifies the custom channel type which is used for channel grouping. The length is limited to 128 characters. |
data | string | Specifies additional channel information such as a long description of the channel or |
is_distinct | boolean | Determines whether to reuse an existing channel or create a new channel when attempting to create a channel with the same group of members. If set to true, returns a channel with the same users in the |
is_public | boolean | Determines whether to allow users to join the channel without an invitation. If set to true, users can join without an invitation. (Default: false) |
is_super | boolean | Determines whether to allow the channel to accommodate 100 or more members. If set to true, creates a Supergroup channel. (Default: false) |
is_ephemeral | boolean | Determines whether to preserve messages in the channel for the purpose of retrieving chat history. If set to true, messages in the channel are not preserved. (Default: false) |
access_code | string | Specifies the access code that is only applicable to public group channels. If specified, the |
inviter_id | string | Specifies the ID of the user who invites other users to the channel. The inviter isn't automatically registered to the channel as a member, so you should specify the ID of the inviter in the |
strict | boolean | Determines whether to receive a |
invitation_status | object | Specifies one or more key-value pair items which set the invitation status of each user invited to the channel. Each key-value pair should be specified with the ID of invited user, a colon (:), and the user’s invitation status (for example, user_id_1: invitation status). Acceptable values are joined, invited_by_friend, and invited_ by_non_friend. (Default: joined) |
hidden_status | object | Specifies one or more key-value pair items which set the channel's hidden status for each user. The value in |
operator_ids[] | array of strings | Specifies an array of one or more IDs of users to register as operators of the channel. You should also include these IDs in the |
block_sdk_user_channel_join | boolean | Determines whether to block users from joining the channel through the Chat SDK. If set to true, users can only join the channel using the join a channel API. (Default: false) |
Note: If you want to upload a profile picture by passing an image
file
instead of a URL, see Multipart requests.
If successful, this action returns a group channel resource in the response body.
Note : The
role
property in each user resource under themember
property indicates whether the user is a channel operator or a channel member.
Creating a Supergroup channel follows the same approach as creating a group channel with the is_super
property as the only exception. The is_super
property needs to be set to true in order to convert a group channel to a Supergroup channel. A Supergroup channel can't be converted to a group channel but a group channel can be converted to a Supergroup channel by changing a value of is_super
to true. Once a group channel has been converted to a Supergroup channel, it can't be switched back to a group channel.
Note: Some features aren't supported for Supergroup channels. For more information, see Supergroup channel's limitations.
The following table lists the properties of an HTTP request that this action supports.
Required
Property name | Type | Description |
---|---|---|
is_super | boolean | Determines whether to create a Supergroup channel. (Default: false) |
Note: Supergroup channels are not supported with the
is_distinct
property and the property is false by default.
If successful, this action returns a Supergroup channel resource in the response body.
In the case of an error, an error object is returned. A detailed list of error codes is available here.