Home

Chat

Platform API

Group channel

A group channel is a chat that allows close interactions among a limited number of users. It can be private or public. A private group channel can let a user join the chat through an invitation by another user who is already a member of the chatroom. For 1-on-1 messaging, you can create a private group channel with two members. A public group chat can let a user join the chat without invitation from others. A group channel can consist of one to one hundred members by default setting. This default number of members can increase per request.

A user can receive all messages from the group channels that they are a member of, and sends a message to those channels. They can also receive push notifications, typing indicators, unread counts and read receipts from their joined channels when they go offline. See the User section for information to turn on and manage the push notifications.

Types of a channel

With our Chat Platform API, you can use a variety of behaviour related properties when creating different types of group channels. You can create a group channel after configuring these properties.

Private vs. Public

A private group channel can be joined only by users that have accepted an invitation from an existing channel member by default. On the other hand, a public group channel can be joined by any user without an invitation, like an open channel.

1-on-1 vs. 1-on-N

A distinct group channel can be reused for the same users. If a user is invited as a new member, or if a member leaves the channel, then the distinct property is automatically disabled. For example, when attempting to create a new group channel with 3 users, A, B, and C, if a channel with same users already exists, a reference to the existing channel is just returned to who has attempted the new channel.

Note: Consequently, we recommend that you turn on the distinct property in 1-on-1 messaging channels to reuse the existing channel when a user directly sends a message to another user. If the property is turned off, a new group channel is created with the same user even if there is a previous chat between them, and you can't see the old messages or data.

Supergroup vs. Group

For occasions that demand engagement among a high volume of members, you can create a Supergroup channel, an expanded version of a group channel. When the super option is set to true, a Supergroup channel will be created and more than 2,000 members can gather in the channel. The maximum number of members in a Supergroup channel varies by your Sendbird plan.

Note: When the is_super is set to true, the distinct option can't be supported.

Ephemeral vs. Persistent

Messages sent in an ephemeral group channel are not saved in Sendbird's database. As such, old messages that are pushed out of a user's chat view due to new messages can't be retrieved. On the other hand, messages sent in a persistent group channel are stored permanently in the database by default.

Resource representation

Property name	Type	Description
name	string	The name of the channel, or the channel topic.
channel_url	string	The unique URL of the channel.
cover_url	string	The URL of the cover image.
custom_type	string	A custom channel type which is used for channel grouping. * Custom types are also used within Sendbird's Advanced analytics to segment metrics, which enables the sub-classification of data views.
data	string	A `string` data which can contain additional channel information such as a long description of the channel or `JSON` formatted string.
is_distinct	boolean	Indicates whether an existing channel is reused or a new channel has been created with a combination of the channel members as well as the custom channel type if specified.
is_public	boolean	Indicates whether to allow a user to join the channel without an invitation.
is_super	boolean	Indicates whether to allow the channel to accommodate more than 2,000 members.
is_ephemeral	boolean	Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history.
is_access_code_required	boolean	Indicates whether to set an access code to the channel and require an access code to a user who attempts to join the channel.
member_count	int	The number of all members who have joined the channel and who have been invited but not joined.
joined_member_count	int	The number of members who have joined the channel only.
members	list	The list of users who are members of the group channel.
operators	list	The list of users registered as operators of the channel. The operators can ban, mute or delete messages in the channel that they join as an operator.
read_receipt	nested object	The timestamps of when each member has last read the messages in the channel, in Unix milliseconds. Each key-value pair has a key with the unique ID of a user and a value with the user’s timestamp.
max_length_message	int	The maximum length of a message allowed to be sent within the channel. This is the same as the value set in the global application settings' max_message_length property.
unread_message_count	int	The number of a specific user's unread messages within the channel. If a user is not specified in the request, the value of this property is 0. However if you specify a user in the request when using such as the list my group channels action, the value is not 0.
unread_mention_count	int	The number of messages which a specific user has been mentioned but has not read within the channel. If a user is not specified in the request, the value of this property is 0. However if you specify a user in the request when using such as the list my group channels action, the value is not 0.
last_message	nested object	The last message that was sent within the channel.
created_by	nested object	The information of the user who created the channel and invited other users as its members. This consists of user_id, nickname, profile_url, and require_auth_for_profile_image properties. The require_auth_for_profile_image indicates whether or not the profile image of the channel creator can be accessed only by other channel members within the application.
created_at	long	The timestamp of when the channel was created, in Unix seconds format.
freeze	boolean	Indicates whether the channel is currently frozen. A value of true indicates that normal members can't chat with each other within the channel but the operators can.
~~channel~~	nested object	*(Deprecated)* An object that exists only for backward compatibility.

Actions

API endpoints are relative to the base URL allocated to the application. The /group_channels endpoint in this page refers to https://api-{application_id}.sendbird.com/v3/group_channels.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID, API request URL.

It's recommended that the parameter values in API URLs be urlencoded, such as {user_id} and {channel_url}.

Managing channels

Action	HTTP request
List channels	`GET` /group_channels Retrieves a list of group channels in the application. If you want to get a list of a specific user's group channels, use the list my group channels action instead.
View a channel	`GET` /group_channels/{channel_url} Retrieves information on a specific group channel.
Create a channel	`POST` /group_channels Creates a group channel.
Update a channel	`PUT` /group_channels/{channel_url} Updates information on a specific group channel.
List members	`GET` /group_channels/{channel_url}/members Retrieves the members of a specific group channel.
Check if member	`GET` /group_channels/{channel_url}/members/{user_id} Checks whether the user is a member of a specific group channel.
Invite as members	`POST` /group_channels/{channel_url}/invite Invites one or more users as members into a specific private group channel.
Accept an invitation	`PUT` /group_channels/{channel_url}/accept Accepts an invitation from a specific private group channel for a user to join.
Decline an invitation	`PUT` /group_channels/{channel_url}/decline Declines an invitation for a user not to join a specific private group channel.
Join a channel	`PUT` /group_channels/{channel_url}/join Allows a user to join a specific public group channel. This is only permitted for public group channels where the is_public property is true.
Leave a channel	`PUT` /group_channels/{channel_url}/leave Makes one or more users leave a specific group channel.
Hide or archive a channel	`PUT` /group_channels/{channel_url}/hide Hides or archives a specific group channel from a user’s group channel list.
Unhide or unarchive a channel	`DELETE` /group_channels/{channel_url}/hide Unhides or unarchives a specific group channel and gets the channel appeared back in a user’s group channel list.
Reset chat history	`PUT` /group_channels/{channel_url}/reset_user_history Resets a user's chat history in a specific group channel.
Freeze a channel	`PUT` /group_channels/{channel_url}/freeze Freezes a specific group channel.
Delete a channel	`DELETE` /group_channels/{channel_url} Deletes a specific group channel.

Operators of channels

Action	HTTP request
List operators	`GET` /group_channels/{channel_url}/operators Retrieves a list of operators of a specific group channel.
Register operators	`POST` /group_channels/{channel_url}/operators Registers a list of one or more users to be assigned as operators of a specific group channel.
Cancel the registration of operators	`DELETE` /group_channels/{channel_url}/operators Cancels the registration of operators from a specific group channel.

Moderation for channels

Action	HTTP request
List banned users	`GET` /group_channels/{channel_url}/ban Retrieves a list of the banned users from a specific group channel.
View a ban	`GET` /group_channels/{channel_url}/ban/{banned_user_id} Retrieves details of a ban imposed on the user.
Ban a user	`POST` /group_channels/{channel_url}/ban Bans a user from a specific group channel.
Update a ban	`PUT` /group_channels/{channel_url}/ban/{banned_user_id} Updates details of a ban imposed on the user.
Unban a user	`DELETE` /group_channels/{channel_url}/ban/{banned_user_id} Unbans the user from a specific group channel.
List muted users	`GET` /group_channels/{channel_url}/mute Retrieves a list of the muted users in a specific group channel.
View a mute	`GET` /group_channels/{channel_url}/mute/{muted_user_id} Retrieves details of a mute imposed on the user.
Mute a user	`POST` /group_channels/{channel_url}/mute Mutes a user in a specific group channel.
Unmute a user	`DELETE` /group_channels/{channel_url}/mute/{muted_user_id} Unmutes the user in a specific group channel.

List channels

Retrieves a list of group channels in the application.

Note: If you want to get a list of a specific user's group channels, use the list my group channels action instead.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels

Parameters

The following table lists the parameters that this action supports.

Parameters

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
distinct_mode	string	Restricts the search scope to only retrieve distinct or nondistinct group channels. Acceptable values are limited to the following: - all (default): all group channels are returned. - distinct: only distinct group channels are returned. - nondistinct: only the group channels that are not distinct are returned.
public_mode	string	Restricts the search scope to only retrieve public or private group channels. Acceptable values are limited to the following: - all (default): all the group channels are returned. - private: all the private group channels are returned. - public: all the public group channels are returned.
super_mode	string	Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are all, super, and nonsuper. (Default: all)
created_after	long	Restricts the search scope to only retrieve group channels which have been created after the specified time in Unix seconds format.
created_before	long	Restricts the search scope to only retrieve group channels which have been created before the specified time in Unix seconds format.
show_empty	boolean	Determines whether to include empty channels in the response. Empty channels are channels that have been created but contain no sent messages. (Default: false)
show_member	boolean	Determines whether to include information about the members of each channel in the response. (Default: false)
show_delivery_receipt	boolean	Determines whether to include information about the delivery receipts of each channel in the response. The delivery receipt indicates the timestamp of when each member has last received the messages from Sendbird server in the channel, in Unix milliseconds. (Default: false)
show_read_receipt	boolean	Determines whether to include information about the read receipts of each channel in the response. The read receipt indicates the timestamp of when each member has last read the messages in the channel, in Unix milliseconds. (Default: false)
show_frozen	boolean	Determines whether to include frozen channels in the response. Frozen channels are a channel where no channel members but operators are allowed to send messages. (Default: true)
order	string	Specifies the method to sort a list of results. Acceptable values are limited to the following: - chronological (default): sorts by the time of channel creation in a descending order. (most recently created channels) - latest_last_message: sorts by the time of the last message in a descending order. This is effective only when the user_id is specified. (most recently updated channels) - channel_name_alphabetical: sorts by the channel names in an alphabetical order. - metadata_value_alphabetical: sorts by the value of metadata in an alphabetical order. This is effective only when the metadata_order_key is specified.
user_id	string	Restricts the search scope to only retrieve the target user's group channels. It is recommended to use the list my group channels action instead.
metadata_order_key	string	Specifies the key of an item in metadata. When the value of the order parameter is set to metatdata_value_alphabetical, the results are alphabetically sorted by the value of the item specified by the key.
custom_types	string	Specifies a comma-separated string of one or more custom types to filter the group channels with the corresponding types. Urlencoding each type is recommended (for example, ?custom_types=urlencoded_type_1,urlencoded_type_2). If not specified, all channels are returned, regardless of their custom type.
custom_type_startswith	string	Searches for group channels with the custom type which starts with the specified value. Urlencoding the value is recommended.
channel_urls	string	Specifies a comma-separated string of one or more group channel URLs to restrict the search scope. Urlencoding each channel URL is recommended (for example, ?channel_urls=urlencoded_url_1, urlencoded_url_2).
name	string	Specifies the name of group channels to retrieve.
name_contains	string	Searches for group channels of which names contain the specified value. Note that this parameter is case-insensitive. Urlencoding the value is recommended.
name_startswith	string	Searches for group channels of which names start with the specified value. Note that this parameter is case-insensitive. Urlencoding the value is recommended.
members_exactly_in	string	Searches for group channels with the specified members exactly in. The parameter value should consist of multiple user IDs separated by commas. Only user IDs that match existing users are used for channel search. Urlencoding each ID is recommended (for example, ?members_exactly_in=urlencoded_user_id_1, urlencoded_user_id_2).
members_include_in	string	Searches for group channels that include one or more members in the parameter value. The value should consist of multiple user IDs separated by commas. Only user IDs that match existing users are used for channel search. Urlencoding each ID is recommended (for example, members_include_in= urlencoded_user_id_1, urlencoded_user_id_2).
query_type	string	Specifies a logical condition applied to the members_include_in filter. Acceptable values are either AND or OR. For example, take the case that you specify three members in members_include_in: A, B, and C. AND returns all channels that include all of {A. B, C} as a subset. OR returns channels that include {A}, plus those that include {B}. plus those that include {C}. (Default: AND)
members_nickname	string	Searches for group channels with members whose nicknames match the specified value. Urlencoding the value is recommended.
members_nickname_contains	string	Searches for group channels with members whose nicknames contain the specified value. Note that this parameter is case-insensitive. Urlencoding the value is recommended. * We recommend at least three characters for the parameter value for better search efficiency when you design and implement related features. If you would like to allow one or two characters for searching, use the members_nickname instead to prevent performance issues.
metadata_key	string	Searches for group channels with metadata containing an item with the specified value as its key. This parameter should be specified in conjunction with either the metadata_values or metadata_value_startswith parameters below.
metadata_values	string	Searches for group channels with metadata containing an item with the key specified by the metadata_key parameter above, and the value of that item matches one or more values specified by this parameter. The string should be specified with multiple values separated by commas. Urlencoding each value is recommended (for example, ?metadata_values=urlencoded_value_1, urlencoded_value_2). This parameter should be specified in conjunction with the metadata_key above.
metadata_value_startswith	string	Searches for group channels with metadata containing an item with the key specified by the metadata_key parameter above, and the values of that item start with the specified value by this parameter. Urlencoding the value is recommended. This parameter should be specified in conjunction with the metadata_key above.
metacounter_key	string	Searches for group channels with metacounter containing an item with the specified value as its key. This parameter should be specified in conjunction with the metacounter_values or one of metacounter_value_gt, metacounter_value_gte, metacounter_value_lt, and metacounter_value_lte below.
metacounter_values	string	Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is equal to one or more values specified by this parameter. The string should be specified with multiple values separated by commas. This parameter should be specified in conjunction with the metacounter_key above.
metacounter_value_gt	string	Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is greater than the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.
metacounter_value_gte	string	Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is greater than or equal to the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.
metacounter_value_lt	string	Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is lower than the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.
metacounter_value_lte	string	Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is lower than or equal to the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.
include_sorted_metaarray_in_last_message	boolean	Determines whether to include the sorted_metaarray as one of the last_message’s properties in the response.
~~custom_type~~	string	*(Deprecated)* Returns channels whose custom_type* matches the given value. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be urlencoded.*
~~read_receipt~~	boolean	*(Deprecated)* Superseded by show_read_receipt.
~~member~~	boolean	*(Deprecated)* Superseded by show_member.
~~is_distinct~~	boolean	*(Deprecated)* Superseded by distinct_mode.
~~members_in~~	string	*(Deprecated)* Superseded by members_exactly_in.

Query string example

Light Color Skin

Copy

?limit=5&order=latest_last_message&show_member=true&show_delivery_receipt=true&show_read_receipt=true&members_include_in=Jay&query_type=AND

Response

If successful, in the response body, this action returns a list of the group channel resources.

Note : The role property in each user resource under the member property indicates whether the user is a channel operator or a normal channel member.

Status: 200 OK

Light Color Skin

Copy

{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "is_ephemeral": false,
            "is_access_code_required": false,
            "freeze": false,
            "max_length_message": 500,
            "custom_type": "schedule_on_progress",
            "name": "On the upcoming AWS event",
            "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
            "created_at": 1484185346,
            "created_by": {
                "user_id": "Jin",
                "nickname": "JinJin",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_09_512px.png",
                "require_auth_for_profile_image": false
            },
            "cover_url": "https://sendbird.com/main/img/cover/cover_43.jpg",
            "data": "{u'background_color': u'yellow', u'description': u'preparing presentation'}",
            "member_count": 3,
            "joined_member_count": 3,
            "members": [
                {
                    "user_id": "Jay",
                    "nickname": "Rooster",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
                    "is_active": true,
                    "is_online": false,
                    "last_seen_at": 1542762346134,
                    "state": "joined",
                    "role": "",     // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
                    "metadata": {
                        "location": "New York",
                        "marriage": "Y"
                    }
                },
                ... # More members
            ],
            "delivery_receipt": {
                "Jay": 1542762344162,
                "Jin": 1542394323413,
                "David": 1542543464371
            },
            "read_receipt": {
                "Jay": 1542762343245,
                "Jin": 1542394301402,
                "David": 1542543456343
            },
            "last_message": {
                "message_id": 640903435,
                "type": "MESG",
                "custom_type": "",
                "mention_type": "users",
                "mentioned_users": [],
                "created_at": 1542762343245,
                "updated_at": 0,
                "is_removed": false,
                "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
                "user": {
                    "user_id": "Jay",
                    "nickname": "Rooster",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png"
                    "metadata": {
                        "location": "New York",
                        "marriage": "Y"
                    }
                },
                "message": "Can you please make the presentation for me?",
                "translations": {},
                "data": "",
                "file": {}
            },
            "invited_at": 1542132194342,
            "inviter": {
                "user_id": "Jin",
                "nickname": "JinJin",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_09_512px.png",
                "metadata": {
                    "location": "San Francisco",
                    "marriage": "Y"
                }
            },
            "unread_message_count": 0,
            "unread_mention_count": 0,
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        },
        ... # More group channels
    ],
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX11fUlsWYnMS"
}

Property name	Type	Description
channels[]	list	A list of group channels that match the specified optional parameters.
next	string	The value for the token parameter to retrieve the next page in the result set.

View a channel

Retrieves information on a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to retrieve.

Optional	Type	Description
show_delivery_receipt	boolean	Determines whether to include information about the delivery receipt of each member of the channel in the response. The delivery receipt indicates the timestamp of when each member has last received the messages from Sendbird server in the channel, in Unix milliseconds. (Default: false)
show_read_receipt	boolean	Determines whether to include information about the read receipt of each member of the channel in the response. The read receipt indicates the timestamp of when each member has last read the messages in the channel, in Unix milliseconds. (Default: false)
show_member	boolean	Determines whether to include information about the members of the channel in the response. (Default: false)
~~read_receipt~~	boolean	*(Deprecated)* Superseded by show_read_receipt.
~~member~~	boolean	*(Deprecated)* Superseded by show_member.

Query string example

Light Color Skin

Copy

?show_delivery_receipt=true&show_read_receipt=true&show_member=true

Response

If successful, this action returns a group channel resource in the response body.

Create a channel

Creates a new group channel.

If you are creating a 1-on-1 direct messaging channel for a user, it is recommended that you turn on the distinct property. If the property is turned off, a user can create a new channel even if they have had the previous chat between them, and therefore can't see previously sent messages or data in the new channel. On the other hand, if the distinct property is turned on, every 1-on-1 conversation between the same two users occurs within the same channel.

HTTP request

Light Color Skin

Copy

POST https://api-{application_id}.sendbird.com/v3/group_channels

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_ids[]	array	Specifies an array of one or more IDs of users to invite to the channel. The maximum number of users to be invited at once is 100. The users below and this property can be used interchangeably.
users[]	array	Specifies an array of one or more IDs of users to invite to the channel. The maximum number of users to be invited at once is 100. The user_ids above and this property can be used interchangeably.

Optional	Type	Description
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 cover image for the channel. The length is limited to 2,048 characters.
cover_file	file	Uploads the cover image file for the channel.
custom_type	string	Specifies the custom channel type which is used for channel grouping. The length is limited to 128 characters. * Custom types are also used within Sendbird's Advanced analytics to segment metrics, which enables the sub-classification of data views.
data	string	Specifies additional channel information such as a long description of the channel or `JSON` formatted string.
is_distinct	boolean	Determines whether to reuse an existing channel or create a new channel. If set to true, returns a channel with the same users in the user_ids or users property or creates a new channel if no match is found. Sendbird server can also use the custom channel type in the custom_type property if specified along with the users to return the corresponding channel. If set to false, Sendbird server always creates a new channel with a combination of the users as well as the channel custom type if specified. (Default: false) * Under this property, Sendbird server does not distinguish channels based on other properties such as channel URL or channel name.
is_public	boolean	Determines whether to allow a user to join the channel without an invitation. (Default: false)
is_super	boolean	Determines whether to allow the channel to accommodate more than 2,000 members. (Default: false) * Supergroup channels are not supported with the is_distinct property and the property is false by default.
is_ephemeral	boolean	Determines whether to preserve the messages in the channel for the purpose of retrieving chat history. (Default: false)
access_code	string	This parameter can only be used when the channel operator creates a public group channel. They can set an access code for the corresponding type of channel. The channel then requires the specified access code to a user who attempts to join. If specified, the is_access_code_required property of the channel resource is set to true.
inviter_id	string	Specifies the ID of the user who has invited other users as members of the channel. The inviter is not automatically registered to the channel as a member, so you should specify the ID of the inviter in the user_ids property below if needed.
strict	boolean	Determines whether to receive a `400111` error and cease channel creation when there is at least one non-existing user in the specified user_ids or users property above. If set to false, the channel will be created excluding the non-existing users without receiving the mentioned error. (Default: false)
invitation_status[]	array	Specifies an array of one or more information about the join status of each invited user to the channel. Each item of the array should be specified with a combination of the unique ID of a user in the user_ids or users property, a colon (:), and the user's join status (for example, *user_id_1: join status). Acceptable values are joined, invited_by_friend, and invited_by_non_friend. (Default: joined*)
hidden_status[]	array	Specifies an array of one or more channel hidden statuses about whether to hide the channel from each invited user's list of group channels, and whether to automatically unhide the hidden channel when receiving a new message from other member of that channel. Each item of the array should be specified with a combination of the unique ID of a user in the user_ids or users property, a colon (:), and the channel hidden status (for example, *user_id_1: channel hidden status). Acceptable values are limited to the following: - unhidden (default): the channel is included in when retrieving a list of group channels. - hidden_allow_auto_unhide: the channel automatically gets unhidden when receiving a new message. - hidden_prevent_auto_unhide*: the channel keeps hidden though receiving a new message.
operator_ids[]	array	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 user_ids property to invite them to the channel as members. They can delete any messages in the channel, and also view all messages without any filtering or throttling. The maximum allowed number of operators per channel is 100.
block_sdk_user_channel_join	boolean	Determines whether to block users from joining the channel through the Chat SDK. This parameter can be used in order to restrict the ways for users to join the channel, and only using the join a channel action can add a user to the channel. (Default: false)

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.

Request body example

Light Color Skin

Copy

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "is_distinct": true,
    "inviter_id": "Jay",
    "user_ids": ["Jay", "James", "Young"],
    "invitation_status": {
        "James": "invited_by_friend",
        "Young": "invited_by_non_friend"
    },
    "hidden_status": {
        "Jay": "hidden_allow_auto_unhide"
    },
    "operator_ids": ["Jeff"]
}

Response

If successful, this action returns a group channel resource in the response body.

Note : The role property in each user resource under the member property indicates whether the user is a channel operator or a normal channel member.

Status: 200 OK

Light Color Skin

Copy

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "unread_message_count": 0,
    "data": "",
    "is_distinct": true,
    "is_public": false,
    "is_super": false,
    "is_ephemeral": false,
    "is_access_code_required": false,
    "hidden_state": "hidden_allow_auto_unhide", // This shows the channel hidden status of the inviter.
    "member_count": 3,
    "joined_member_count": 1,
    "members": [
        {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["543-098-4567", "010-4567-6543"],
            "last_seen_at": 1530232836311,
            "state": "joined",
            "role": "",         // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "New York",
                "marriage": "Y"
            }
        },
        {
            "user_id": "James",
            "nickname": "Knight",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_08_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["789-012-7834", "010-1245-3658"],
            "last_seen_at": 1530237133254,
            "state": "invited",     // 'invited_by_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Tokyo",
                "marriage": "N"
            }
        },
        {
            "user_id": "Young",
            "nickname": "Sportsman",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
            "is_active": true,
            "is_online": true,
            "friend_discovery_key": ["357-642-1369", "010-4030-1357"],
            "last_seen_at": 1530232801201,
            "state": "invited",     // 'invited_by_non_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Chicago",
                "marriage": "N"
            }
        }
    ],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        }
    ],
    "max_length_message": 500,
    "last_message": null,
    "created_at": 1543468122,
    "freeze": false,
    "channel": {
        ...     # This key has been deprecated and only exists for backward compatibility.
    }
}

Update a channel

Updates information on a group channel.

Note: You can't change the members of the channel here. To do so, see invite as members action below.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to update.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Optional	Type	Description
name	string	Specifies the name of the channel, or the channel topic. The length is limited to 191 characters.
cover_url	string	Specifies the unique URL of the cover image. The length is limited to 2,048 characters.
cover_file	file	Uploads the cover image file for the channel.
custom_type	string	Specifies the custom channel type which is used for channel grouping. The length is limited to 128 characters. * Custom types are also used within Sendbird's Advanced analytics to segment metrics, which enables the sub-classification of data views.
data	string	Specifies additional channel information such as a long description of the channel or `JSON` formatted string.
is_distinct	boolean	Determines whether to reuse an existing channel or create a new channel. If set to true, returns a channel with the current channel members users or creates a new channel if no match is found. Sendbird server can also use the custom channel type in the custom_type property if specified along with the users to return the corresponding channel. If set to false, Sendbird server always creates a new channel with a combination of the users as well as the channel custom type if specified. (Default: false) * Under this property, Sendbird server does not distinguish channels based on other properties such as channel URL or channel name.
is_public	boolean	Determines whether to allow a user to join the channel without an invitation. (Default: false)
access_code	string	This property can be used only when the channel operator wants to set an access code for a public group channel. If specified, the is_access_code_required property of the channel resource is then set to true, and the channel begins to require the specified access code to a user who attempts to join.
operator_ids[]	array	Specifies an array of one or more IDs of users to register as operators of the channel. If the operators are not members of the channel yet, they need an invitation to join a privte group channel while they don't need any to join a public group channel. The maximum allowed number of operators per channel is 100.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.

Response

If successful, this action returns a group channel resource in the response body.

List members

Retrieves a list of members of a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/members

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to retrieve a list of members of.

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
show_delivery_receipt	boolean	Determines whether to include information about the delivery receipt of each member of the channel in the response. The delivery receipt indicates the timestamp of when each member has last received the messages from Sendbird server in the channel, in Unix milliseconds. (Default: false)
show_read_receipt	boolean	Determines whether to include information about the read receipt of each member of the channel in the response. The read receipt indicates the timestamp of when each member has last read the messages in the channel, in Unix milliseconds. (Default: false)
order	string	Specifies the method to sort a list of results. Aceptabe values are limited to the following: - member_nickname_alphabetical (default): sorts by the member nicknames in an alphabetical order. - operator_then_member_alphabetical: sorts by the operational role listing operators prior to normal members in an alphabetical order.
operator_filter	string	Restricts the search scope to only retrieve members who are the operators of the channel or not. Acceptable values are all, operator, and nonoperator. (Default: all) - all(default): no filter is applied to the list. - operator: only operators are retrieved for the list. - nonoperator: all members, except for operators, are retrieved for the list.
member_state_filter	string	Restricts the search scope to retrieve members based on whether or not they have accepted an invitation or whether or not they were invited by a friend. Acceptable values are invited_only, joined_only, invited_by_friend, invited_by_non_friend, and all. (Default: all)
muted_member_filter	string	Restricts the search scope to retrieve members who are muted in the channel or not. Acceptable values are all, muted, and unmuted. (Default: all)
nickname_startswith	string	Searches for members whose nicknames start with the specified value. Urlencoding the value is recommended.

Query string example

Light Color Skin

Copy

?limit=4&show_delivery_receipt=true&show_read_receipt=true&operator_filter=all

Response

If successful, this action returns a list of user resources registered as members of the channel in the response body.

Note : The role property in each user resource under the member property indicates whether the user is a channel operator or a normal channel member.

Status: 200 OK

Light Color Skin

Copy

{
    "members": [
        {
            "user_id": "Aiden",
            "nickname": "Doctor",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_54_512px.png",
            "is_active": true,
            "is_online": false,
            "state": "joined",
            "role": "operator",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "delivered_ts": 1542762336581,  // The delivery receipt of this member
            "read_ts": 1542762334452,       // The read receipt of this member
            "last_seen_at": 1542762334452,
            "metadata": {
                "location": "Columbus",
                "marriage": "Y"
            }
        },
        ... # More members
    ],
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrDEGNFX11fUlsEfEAf"
}

Property name	Type	Description
members[]	list	A list of the users who are members of the channel.
next	string	The value for the token parameter to retrieve the next page in the result set.

Check if member

Checks whether the user is a member of the group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/members/{user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
user_id	string	Specifies the unique ID of the user to check.

Response

If successful, in the response body, this action returns the is_member property which indicates whether the user is a member of the channel.

Status: 200 OK

Light Color Skin

Copy

{
    "is_member": true
}

Property name	Type	Description
is_member	boolean	Indicates whether the user is a member of the channel.

Invite as members

Invites one or more users as members into the group channel.

Note: By default, users in your application automatically join a private group channel promptly from an invitation without having to accept it. If you want to give them the option to decide whether to accept or decline an invitation, you should set the value of channel invitation preference to false through the update default channel invitation preference action. Or using the update a user's channel invitation preference action, you can also allow the option individually by user.

HTTP request

Light Color Skin

Copy

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/invite

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to invite into.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_ids[]	array	Specifies an array of one or more user IDs to invite into the channel. The maximum number of users to be invited at once is 100. The users can be used instead of this property.
users[]	list	Specifies a list of one or more `JSON` objects which contain the user_id property to invite into the channel. The maximum number of users to be invited at once is 100. The user_ids can be used instead of this property.

Optional	Type	Description
invitation_status[]	array	Specifies an array of one or more information about the join status of each invited user to the channel. Each item of the array should be specified with a combination of the unique ID of a user in the user_ids or users property, a colon (:), and the user's join status (for example, *user_id_1: join status). Acceptable values are joined, invited_by_friend, and invited_by_non_friend. (Default: joined*)
hidden_status[]	array	Specifies an array of one or more channel hidden statuses about whether to hide the channel from each invited user's list of group channels, and whether to automatically unhide the hidden channel when receiving a new message from other member of that channel. Each item of the array should be specified with a combination of the unique ID of a user in the user_ids or users property, a colon (:), and the channel hidden status (for example, *user_id_1: channel hidden status). Acceptable values are limited to the following: - unhidden (default): the channel is included in when retrieving a list of group channels. - hidden_allow_auto_unhide: the channel automatically gets unhidden when receiving a new message. - hidden_prevent_auto_unhide*: the channel keeps hidden though receiving a new message.

user_ids

users

Light Color Skin

Copy

# Request body example
{
    "user_ids": ["Fluo", "Justin", "Chris"],
    "invitation_status": {
        "Fluo": "invited_by_friend",
        "Justin": "invited_by_non_friend"
    },
    "hidden_status": {
        "Chris": "hidden_allow_auto_unhide"
    }
}

Light Color Skin

Copy

# Request body example
{
    "users": [
        {
            "user_id": "Fluo"
        },
        {
            "user_id": "Justin"
        },
        {
            "user_id": "Chris"
        }
    ],
    "invitation_status": {
        "Fluo": "invited_by_friend",
        "Justin": "invited_by_non_friend"
    },
    "hidden_status": {
        "Chris": "hidden_allow_auto_unhide"
    }
}

Response

If successful, this action returns a group channel resource in the response body.

Accept an invitation

Accepts an invitation from a private group channel for a user to join. Since a user is allowed to join up to 2,000 group channels, the invitation to a user who already belongs to a maximum number of group channels will be canceled automatically.

Note: This action is effective only when the auto_accept property of an application is set to false. You can change the value of the property using the update default channel invitation preference action, or update a user's channel invitation preference action.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/accept

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the private group channel to join through accepting an invitation.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user to accept an invitation to join the private group channel.

Optional	Type	Description
access_code	string	This property should be specified if the private group channel to join requires an access code to the invited users, which means that the is_access_code_required property of the channel resource is true.

Response

If successful, this action returns a group channel resource in the response body.

Decline an invitation

Declines an invitation for a user to not join a private group channel.

Note: This action is effective only when the auto_accept property of an application is set to false. You can change the value of the property using the update default channel invitation preference action, or update a user's channel invitation preference action.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/decline

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the private group channel to decline an invitation from.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user to decline an invitation.

Response

If successful, this action returns an empty response body.

Join a channel

Allows a user to join a public group channel. Since a user is allowed to join up to 2,000 group channels, a user who already belongs to a maximum number of group channels can’t join a new channel.

Note: This action is only permitted for public group channels where the is_public property is true.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/join

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to join.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user to join the public group channel.

Optional	Type	Description
access_code	string	This property should be specified if the public group channel to join requires an access code to users, which means that the is_access_code_required property of the channel resource is true.

Response

If successful, this action returns an empty response body.

Leave a channel

Makes one or more members leave a group channel.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/leave

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to leave.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Optional	Type	Description
user_ids[]	array	Specifies an array of one or more IDs of the users to leave the channel.
should_leave_all	boolean	Determines whether to make all members leave the channel. (Default: false)

Request body example

Light Color Skin

Copy

{
    "user_ids": ["Philip", "Matthew", "Janna"]
}

Response

If successful, this action returns an empty response body.

Hide or archive a channel

Hides or archives a channel from the channel list of either a specific user or entire channel members. Normally, a hidden channel comes back and shows up in the channel list when a member in the channel sends a new message. This automatically-triggered behavior is intended for users who want to temporarily remove a channel from their list because leaving the channel would delete all the past messages and stored data.

You can also leave out a channel from the list and archive the channel. The channel doesn't appear even when receiving a new message from other member.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/hide

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to hide or archive.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user whose channel will be hidden or archived from the list. This property is required when should_hide_all is set to false, which is the default value. However, when should_hide_all is set to true, this property isn't effective.

Optional	Type	Description
allow_auto_unhide	boolean	Determines the state and operating behavior of the channel in a channel list. If set to true, the channel is hidden from a user’s channel list but it will reappear when there is a new message. If set to false, the channel is hidden from a user’s channel list and it will remain hidden unless the value of the property changes to true through unarchiving. (Default: true) * When a user who has hidden the channel sends a message in that channel through the Platform API, the `allow_auto_unhide` property is changed to true, making the channel reappear in the channel list.
should_hide_all	boolean	Determines whether to make the specified channel disappear from the channel list of all channel members. When this is set to true, the user_id property isn't effective and doesn't need to be specified in the request. (Default: false)
hide_previous_messages	boolean	When the channel gets appeared back in either the list of the user in the user_id property or the lists of all channel members (should_hide_all = true), determines whether to conceal the messages sent and received before hiding or archiving the channel. (Default: false) * This property is effective only when the value of the global application settings resource's display_past_message property is false.

Response

If successful, this action returns an empty response body.

Unhide or unarchive a channel

Makes a hidden or archived channel reappear in the channel list of either a specific user or entire channel members.

HTTP request

Light Color Skin

Copy

DELETE https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/hide

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to unhide or unarchive.
user_id	string	Specifies the unique ID of the user whose hidden or archived channel will be reappear in the list. This property is required when should_unhide_all is set to false, which is the default value. However, when the should_unhide_all value is true, this property isn't effective. Urlencoding the value is recommended (for example, ?user_id=urlencoded_id).

Optional	Type	Description
should_unhide_all	boolean	Determines whether to make the hidden or archived channel appear back in the channel list of all channel members. When this is set to true, the user_id property isn't effective and doesn't need to be specified in the request. (Default: false)

Query string example

Light Color Skin

Copy

?user_id=Jeff

Response

If successful, this action returns an empty response body.

Reset chat history

Resets the properties related to a user’s chat history in a group channel, then clears the existing messages in the channel on the user’s side only. A user can no longer see the messages in a group channel once this action is called, but those messages are not deleted from the database of the Sendbird system. All other members in the channel can retrieve and see the messages.

This action simply clears the messages for the user by updating the last_message and read_receipt properties of the channel resource in addition to other internally managed data such as the number of the user’s unread message.

Using the reset_all property, you can also reset the properties related to all users' chat history in a group channel.

Note: This action is effective only when the display_past_message property of the global application settings is set as false. You can change the value of the property using the update the settings action. You can also turn on and off the related option in your dashboard: Settings > Chat > Messages > Channel history.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/reset_user_history

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel to reset chat history.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user whose chat history to reset in the channel. If this user_id property is specified, the reset_all property is not required.
reset_all	boolean	Determines whether to reset all users' chat history in the channel. If this reset_all property is specified, the user_id property is not required.

Request body example

Light Color Skin

Copy

{
    "user_id": "Ki-eun"
}

Response

If successful, this action returns an empty response body.

Freeze a channel

Freezes or unfreezes a group channel.

Note: Only users designated as channel operators are allowed to talk when a channel is frozen.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/freeze

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to freeze.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
freeze	boolean	Determines whether to freeze the channel. (Default: false)

Response

If successful, this action returns a group channel resource in the response body.

Delete a channel

Deletes a group channel.

HTTP request

Light Color Skin

Copy

DELETE https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to delete.

Response

If successful, this action returns an empty response body.

List operators

Retrieves a list of operators of a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to retrieve a list of operators.

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example

Light Color Skin

Copy

?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=5

Response

If successful, this action returns a list of user resources registered as operators of the channel in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        },
        ... # More operators
    ],
    "next": "EK1VV3dFQVErEUBXWFNeFp3Q2Fkfe2~~"
}

Property name	Type	Description
operators[]	list	A list of the users who are registered as the operators of the channel.
next	string	The value for the token parameter to retrieve the next page in the result set.

Register operators

Registers one or more operators to a group channel.

HTTP request

Light Color Skin

Copy

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to register operators to.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
operator_ids[]	array	Specifies an array of one or more IDs of users to register as operators of the channel. If the operators are not members of the channel yet, they need an invitation to join a privte group channel while they don't need any to join a public group channel. The maximum allowed number of operators per channel is 100.

Request body example

Light Color Skin

Copy

{
    "operator_ids": ["Jeff", "Glen", "Caroline"]
}

Response

If successful, this action returns an empty response body.

Cancel the registration of operators

Cancels the registration of operators from a group channel but leave them as members.

HTTP request

Light Color Skin

Copy

DELETE https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to cancel the registration of operators.
operator_ids[]	array	Specifies an array of one or more operator IDs to cancel the registration of operators from the channel. The operators in this array remain as the members of the channel after losing their operational roles. Urlencoding each operator ID is recommended (for example, ?operator_ids=urlencoded_id_1,urlencoded_id_2).

Optional	Type	Description
delete_all	boolean	Determines whether to cancel the registration of all operators and leave them as the members of the channel. When this is set to true, the operator_ids property isn't effective and doesn't need to be specified in the request. (Default: false)

Query string example

Light Color Skin

Copy

?operator_ids=Jeff,Glen

Response

If successful, this action returns an empty response body.

List banned users

Retrieves a list of the banned users from a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/ban

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel where to retrieve a list of banned users.

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit	int	Specifies the number of results to return per page. This value must be between 1 and 100. (Default: 10)

Query string example

Light Color Skin

Copy

?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=5

Response

If successful, this action returns a list of banned user resources and information on each ban in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "banned_list": [
        {
            "user": {
                "user_id": "John",
                "nickname": "Sendbirdian",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_02_512px.png",
                "metadata": {
                    "location": "San Mateo",
                    "marriage": "Y"
                }
            },
            "start_at": 1543211671000,
            "end_at": 1543211731000,
            "description": "Too much talking"
        },
        ... # More bans
    ],
    "next": "ANQ12DaZR1nRFn1YzlVaR4rF"
}

Property name	Type	Description
banned_list[]	list	A list of the bans which contain information on the user, ban period, and reason.
banned_list[].(ban).user	nested object	The user resource which contains the simplified information on the banned user.
banned_list[].(ban).start_at	long	The timestamp of when the ban starts, in Unix milliseconds.
banned_list[].(ban).end_at	long	The timestamp of when the ban is scheduled to end, in Unix milliseconds.
banned_list[].(ban).description	string	A reason for the banning.
next	string	The value for the token parameter to retrieve the next page in the result set.

View a ban

Retrieves details of a ban imposed on a user.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
banned_user_id	string	Specifies the ID of the banned user to retrieve.

Response

If successful, this action returns a user resource and information on a ban in the response body.

Ban a user

Bans a user from a group channel. A banned user is immediately expelled from a channel and allowed to join the channel again after a set time period.

HTTP request

Light Color Skin

Copy

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/ban

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel where to ban a user.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the unique ID of the user to ban.

Optional	Type	Description
agent_id	string	Specifies the ID of the agent (operator) who bans the user.
seconds	int	Specifies the ban duration. If set to -1, the user will be banned permanently (10 years, technically). (Default: -1)
description	string	Specifies a reason for the banning. The length is limited to 250 characters.

Request body example

Light Color Skin

Copy

{
    "user_id": "John",
    "seconds": 60,
    "description": "Too much talking"
}

Response

If successful, this action returns a user resource and information on a ban in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "user": {
        "user_id": "John",
        "nickname": "Sendbirdian",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_02_512px.png",
        "metadata": {
            "location": "San Mateo",
            "marriage": "Y"
        }
    },
    "start_at": 1543211671000,
    "end_at": 1543211731000,
    "description": "Too much talking"
}

Property name	Type	Description
user	nested object	The user resource which contains the simplified information on the banned user.
start_at	long	The timestamp of when the ban starts, in Unix milliseconds.
end_at	long	The timestamp of when the ban is scheduled to end, in Unix milliseconds.
description	string	A reason for the banning.

Update a ban

Updates details of a ban imposed on a user. You can change the length of the ban with this action, and also provide an updated description.

HTTP request

Light Color Skin

Copy

PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
banned_user_id	string	Specifies the ID of the banned user to update.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Optional	Type	Description
seconds	int	Specifies a new ban duration to update. If set to -1, the user will be banned permanently (10 years, technically).
description	string	Specifies a new reason for the banning to update. The length is limited to 250 characters.

Response

If successful, this action returns a user resource and information on a ban in the response body.

Unban a user

Unbans a user from a group channel.

HTTP request

Light Color Skin

Copy

DELETE https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
banned_user_id	string	Specifies the unique ID of the user to unban.

Response

If successful, this action returns an empty response body.

List muted users

Retrieves a list of the muted users in a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/mute

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the channel to retrieve a list of muted users.

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example

Light Color Skin

Copy

?token=&limit=5

Response

If successful, this action returns a list of muted user resources and information on the users' mutings in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "muted_list": [
        {
            "user_id": "Kelly",
            "nickname": "Traveler",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_89_512px.png",
            "metadata": {
                "location": "Las Vegas",
                "marriage": "N"
            },
            "remaining_duration": -1,
            "end_at": -1,
            "description": "too many messages in the channel"
        },
        {
            "user_id": "Aiden",
            "nickname": "Renegade",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_48_512px.png",
            "metadata": {
                "location": "Columbus",
                "marriage": "Y"
            },
            "remaining_duration": 21253000,
            "end_at": 1542722786000,
            "description": "relationless messages"
        },
        ... # More muted users
    ],
    "next": "b4FSR3E8Q1ARFeVfWlVZE43LAr~~"
}

Property name	Type	Description
muted_list[]	list	A list of the muted users
next	string	The value for the token parameter to retrieve the next page in the result set.

View a mute

Checks if a user is muted in a group channel.

HTTP request

Light Color Skin

Copy

GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/mute/{muted_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
muted_user_id	string	Specifies the unique ID of the user to check.

Response

If successful, this action returns information on a user's muting in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "is_muted": true,
    "remaining_duration": 38126218,
    "start_at": 1543287589000,
    "end_at": 1543331132000,
    "description": "relationless messages"
}

Property name	Type	Description
is_muted	boolean	Indicates whether the user is muted in the channel.
remaining_duration	long	The remaining duration, measured in Unix milliseconds, from the start of the muting to the end_at below which indicates when the user gets unmuted in the channel. A value of -1 indicates that no time limit is imposed on the muting. (Default: -1)
start_at	long	The time in seconds when the user gets muted in the channel. The value is in Unix milliseconds format.
end_at	long	The time in seconds when the user gets unmuted in the channel. The value is in Unix milliseconds format. A value of -1 indicates that no time limit is imposed on the muting. (Default: -1)
description	string	A reason for the muting.

Mute a user

Mutes a user in a group channel. A muted user remains in the channel and is allowed to view the messages, but can't send any messages until unmuted.

HTTP request

Light Color Skin

Copy

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/mute

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_id	string	Specifies the ID of the target user to mute.

Optional	Type	Description
seconds	long	Specifies the duration of mute status. If set to -1, the user will be muted permanently (10 years, technically). (Default: -1)
description	string	Specifies a reason for the muting.

Response

If successful, this action returns a group channel resource in the response body.

Unmute a user

Unmutes a user within a group channel.

HTTP request

Light Color Skin

Copy

DELETE https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/mute/{muted_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
channel_url	string	Specifies the URL of the target channel.
muted_user_id	string	Specifies the unique ID of the user to unmute.

Response

If successful, this action returns an empty response body.

Open channel

Announcements