Group Channel

Group Channel is a chat that provides close interactions among limited number of people. The group channel can be private or a 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. A group channel can consist of one to one hundred members by default setting. This default number of members can increase per request.

Users receive all messages from the group channels that they are a member of. And they can receive push notifications, typing indicators, unread counts and read receipts from these channels when they go offline. See the User section for information to turn on and manage the push notifications.


A Private group channel (default setting) can be accessed only by users that have accepted an invitation by an existing member of that group. On the other hand, a Public group channel can be accessed by any user without an invitation, like an open channel.

Messages sent in an Ephemeral group channel are not saved in SendBird infrastructure's database. As such, the old messages that scroll up beyond the user's display due to new messages cannot be retrieved. On the other hand, messages sent in a Persistent group channel (default setting) are stored permanently in the database.

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

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 a friend. If the property is turned off, a new group channel is created with the same friend even if there is a previous chat between them, and you can't see the old messages or data.


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.
cover_file file The file of the cover image.
custom_type string A field used to further subclassify the channel.
data string Additional data that you can store within a channel.
is_public boolean Whether the channel is public or private.
is_ephemeral boolean Whether the channel is ephemeral or not.
is_distinct boolean Whether the channel is Distinct. A channel with the Distinct property turned on is reused for the same members. If a new member is invited, or if a member leaves the channel, then the distinct property is disabled automatically. For example, in the case that a group channel with 3 members, A, B, and C, already exists, attempting to create a new channel with the same members just returns a reference to the existing channel.
member_count int The number of members in the channel.
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 user has last read the messages in the channel, in Unix milliseconds.
max_length_message int The maximum length of a message allowed to be sent within the channel. If set to -1, the length is unlimited.
unread_message_count int The number of a specific user's unread messages within the channel. In the general group channel instance, the value of this field is 0. When you fetch the single user's channels with List my group channels, the value is not 0.
last_message nested object The last message that was sent within the channel.
created_at long The timestamp of when the channel was created. The value is in Unix seconds format.
freeze boolean Whether the channel is currently frozen. If true, then ordinary members cann't chat within the channel.
channel nested object (Deprecated) An object that exists only for backward compatibility.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /group_channels endpoint refers to https://{region_identifier}.sendbird.com/v3/group_channels.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Create a channel POST /group_channels Creates a group channel.
List channels GET /group_channels Returns a list of the group channels in the application.
Update the channel PUT /group_channels/{channel_url} Updates the channel’s information.
View the channel GET /group_channels/{channel_url} Returns the channel’s information.
Delete the channel DELETE /group_channels/{channel_url} Deletes the group channel.
List members GET /group_channels/{channel_url}/members Returns the members of the channel.
Check if member GET /group_channels/{channel_url}/members/{user_id} Returns whether the user is a member of the group channel.
Invite members POST /group_channels/{channel_url}/invite Invites a new user into the group channel.
Hide the channel PUT /group_channels/{channel_url}/hide Hides the group channel from a user’s group channel list.
Join the channel PUT /group_channels/{channel_url}/join Allows a user join the public group channel. Only permitted for public group channels where is_public with true
Leave the channel PUT /group_channels/{channel_url}/leave Makes user(s) leave the group channel.
Freeze the channel PUT /group_channels/{channel_url}/freeze Freezes the channel.
Action HTTP request Description
Add operators PUT /group_channels/{channel_url}/operators Add a list of users to be assigned as operators of the group channel.
List operators GET /group_channels/{channel_url}/operators List the operators of the group channel.
Remove operators DELETE /group_channels/{channel_url}/operators Remove a list of the operators from the group channel.
Action HTTP request Description
Ban the user POST /group_channels/{channel_url}/ban Bans the user from the channel.
List banned users GET /group_channels/{channel_url}/ban Returns a list of the banned users in the channel.
Update the ban PUT /group_channels/{channel_url}/ban/{banned_user_id} Updates details of a ban imposed on the user.
View the ban GET /group_channels/{channel_url}/ban/{banned_user_id} Returns details of a ban imposed on the user.
Unban the user DELETE /group_channels/{channel_url}/ban/{banned_user_id} Unbans the user.
Mute the user POST /group_channels/{channel_url}/mute Mutes a user.
List muted users GET /group_channels/{channel_url}/mute Returns a list of the muted users in the channel.
View the mute GET /group_channels/{channel_url}/mute/{muted_user_id} Returns details of a mute imposed on the user.
Unmute the user DELETE /group_channels/{channel_url}/mute/{muted_user_id} Unmutes the user.

Create a channel

Creates a 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 previous conversations with a friend, and therefore can't see previously sent messages or data. 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.

POST https://{region_identifier}.sendbird.com/v3/group_channels
Property name Type Description
name (optional) string The name of the channel, or the channel topic. The length is limited to 1,024 bytes. (Default: Group Channel)
channel_url (optional) string The URL of the channel. Only numbers, characters, and underscores are allowed. The length is 4 to 100 bytes, inclusive. If not specified, a URL is automatically generated.
cover_url (optional) string The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the cover image.
custom_type (optional) string A field used to further subclassify the channel. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within a channel.
user_ids[] (optional) list The string IDs of the users to invite into the channel. The maximum number of users to be invited at once is 100.
operator_ids[] (optional) list The string IDs of the users registered as channel operators. The operator IDs also should be included in the user_ids property to be the members of a channel. They can delete any messages in the channel, and also view all messages in the channel without any filtering or throttling. The maximum number of operators for the channel is 100.
is_distinct (optional) boolean Whether the channel is distinct. (Default: false)
is_public (optional) boolean Whether the channel is public or private. (Default: false)
is_ephemeral (optional) boolean Whether the channel is ephemeral or not. (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
{
    "name": "Chat with Lizzy",
    "channel_url": "group_channel_1",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "personal",
    "data": "",
    "user_ids": ["terry5", "elizabeth2"],
    "operator_ids": ["terry5", "elizabeth2"],
    "is_distinct": true
}

Returns a group channel representation.

Status: 200 OK
{
    "unread_message_count": 0,
    "max_length_message": -1,
    "is_distinct": true,
    "name": "Chat with Lizzy",
    "member_count": 2,
    "custom_type": "personal",
    "is_ephemeral": false,
    "data": "",
    "created_at": 1532744143,
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "freeze": false,
    "last_message": null,
    "members": [
        {
            "state": "joined",
            "friend_discovery_key": null,
            "user_id": "terry5",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 1530232836311,
            "nickname": "Lydia",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_37_512px.png",
            "metadata": {}
        },
        {
            "state": "joined",
            "friend_discovery_key": null,
            "user_id": "elizabath",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 1530816367663,
            "nickname": "test",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_31_512px.png",
            "metadata": {}
        }
    ],
    "is_public": false,
    "is_super": false,
    "joined_member_count": 2,
    "channel_url": "group_channel_1",
    "channel": {
        ... # This key has been deprecated and only exists for backward compatibility.
    }
}

List channels

Returns a list of the group channels in an application.

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

GET https://{region_identifier}.sendbird.com/v3/group_channels
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
show_member boolean Whether to include member information in the response body. (Default: false)
show_read_receipt boolean Whether to include read_receipt information in the response body. (Default: false)
distinct_mode string Possible values are distinct, nondistinct, and all. If distinct is specified, only Distinct channels are returned. If nondistinct is specified, only the channels that are not Distinct are returned. (Default: all)
public_mode string Possible values are private, public, and all. If private is given, all the private group channels are returned. If public is given, all the public group channels are returned. If all is given, all the group channels are returned. (Default: all)
members_exactly_in string Search for channels with exactly the specified members. The string passed here must be urlencoded, with multiple IDs separated by commas. (for example, url_encoded_id_1, url_encoded_id_2)
members_include_in string Search for channels that include the specified members. Use in conjunction with the query_type parameter. The string passed here must be urlencoded, with multiple IDs separated by commas. (for example, url_encoded_id_1, url_encoded_id_2)
members_nickname_contains string Search for channels that include members with the specified nicknames. The string passed here must be urlencoded, with multiple nicknames separated by commas. (for example, url_encoded_nickname_1,url_encoded_nickname_2)
query_type string A logical condition applied to the members_include_in filter. Possible 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)
custom_types string Search for channels with the specified custom types. The string passed here must be urlencoded, with multiple custom types separated by commas. (for example, url_endcoded_custom_type_1, url_encoded_custom_type_2). If this field is not specified, all channels are returned, regardless of their custom type.
channel_urls string Search for channels with the specified URLs. The string passed here must be urlencoded, with multiple URLs separated by commas. (for example, url_encoded_channel_1, url_encoded_channel_2)
created_after long The starting timestamp of the query, in Unix seconds format.
created_before long The ending timestamp of the query, in Unix seconds format.
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.
user_id string (Deprecated) Superseded by List my group channels. Search the given user's channels.
order string (Deprecated) Possible values are latest_last_message and chronological. If chronological is specified, channels are sorted in the order they were created (most recent listed first). If latest_last_message is specified, channels are sorted by the time of their last message (most recent listed first). (Default: chronological)
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.
show_empty boolean (Deprecated) Superseded by my_group_channels.
Request example
?members_include_in=terry5,elizabeth2&query_type=AND

Returns a list of group channels.

Status: 200 OK
{
    "channels": [
        {
            "unread_message_count": 0,
            "is_distinct": false,
            "custom_type": "",
            "last_message": {
                "created_at": 1484037029949,
                "user": {
                    "nickname": "Lizzy",
                    "user_id": "elizabeth2",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
                },
                "custom_type": "",
                "data": "",
                "message": "when are we going to shanghai?",
                "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
                "type": "MESG",
                "message_id": 637718485
            },
            "cover_url": "https://sendbird.com/main/img/cover/cover_07.jpg",
            "data": "",
            "name": "Trip to Shanghai",
            "member_count": 4,
            "created_at": 1484037012,
            "max_length_message": -1,
            "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        },
        {
            "unread_message_count": 0,
            "is_distinct": false,
            "custom_type": "",
            "last_message": {
                "created_at": 1484036870591,
                "user": {
                    "nickname": "Lizzy",
                    "user_id": "elizabeth2",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
                },
                "custom_type": "",
                "data": "",
                "message": "how are you doing?",
                "channel_url": "sendbird_group_channel_24896175_1062a6074f982c05f9c49c6111ccae49eba096b3",
                "type": "MESG",
                "message_id": 637716201
            },
            "cover_url": "https://sendbird.com/main/img/cover/cover_09.jpg",
            "data": "",
            "name": "Chat with Terry",
            "member_count": 2,
            "created_at": 1484036361,
            "max_length_message": -1,
            "channel_url": "sendbird_group_channel_24896175_1062a6074f982c05f9c49c6111ccae49eba096b3",
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        }
    ],
    "next": ""
}
Property name Type Description
channels[] list A list of group channels that match the specified optional parameters.
next string The token for the next chunk of results.

Update the channel

Updates the channel’s information.

Note: You cannot change the members of the channel here. To do so, see Invite users.

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Property name Type Description
name (optional) string The name of the channel, or the channel topic. The length is limited to 1,024 bytes.
cover_url (optional) string The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the cover image.
custom_type (optional) string A field used to further subclassify the channel. The length is limited to 128 bytes.
data (optional) string Additional data that you can store within a channel.
is_distinct (optional) boolean Whether the channel is distinct.
is_public (optional) boolean Whether the channel is public or not.(Default:false) We allow changing this value to a different value after the channel is created.
is_ephemeral (optional) boolean Whether the channel is ephemeral or not.(Default:false) We allow changing this value to a different value after the channel is created.

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
{
    "name": "Art project",
    "description": "We will discuss our art project in this room."
}

Returns a group channel representation.

Status: 200 OK
{
    "unread_message_count": 0,
    "is_distinct": true,
    "custom_type": "personal",
    "last_message": null,
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "members": [
        {
            "nickname": "Terry",
            "last_seen_at": 1484803356516,
            "user_id": "terry5",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
            "is_online": false
        },
        {
            "nickname": "Lizzy",
            "last_seen_at": 1484797001824,
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
            "is_online": false
        }
    ],
    "data": "",
    "name": "Art project",
    "member_count": 2,
    "created_at": 1484795671,
    "max_length_message": -1,
    "channel_url": "sendbird_group_channel_24896175_9771eff89d8d2bbdb7269f95a3bf554ef31f9962",
    "channel": {
        ... # This key has been deprecated and only exists for backward compatibility.
    }
}

View the channel

Returns the channel’s information.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Parameter name Type Description
show_read_receipt boolean Whether to include read_receipt information in the response body. (Default: false)
show_member boolean Whether to include member information in the response body. (Default: false)
read_receipt boolean (Deprecated) Superseded by show_read_receipt.
member boolean (Deprecated) Superseded by show_member.
Request example
?show_read_receipt=true

Returns a group channel representation.

Status: 200 OK
{
    "unread_message_count": 0,
    "is_distinct": false,
    "is_public": false,
    "is_ephemeral": false,
    "custom_type": "",
    "last_message": {
        "created_at": 1484111385098,
        "user": {
            "nickname": "Bunny",
            "user_id": "rabbit",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "hi liz",
        "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
        "type": "MESG",
        "message_id": 638756582
    },
    "read_receipt": {
        "jack2": 1484111579875,
        "elizabeth2": 1484111340910,
        "terry5": 0,
        "rabbit": 1484111379930
    },
    "cover_url": "https://sendbird.com/main/img/cover/cover_07.jpg",
    "data": "",
    "name": "Trip to Shanghai",
    "member_count": 4,
    "created_at": 1484037012,
    "max_length_message": -1,
    "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
    "channel": {
        ... # This key has been deprecated and only exists for backward compatibility.
    }
}
Property name Type Description
read_receipt nested object The timestamps of when each user has last read the messages in the channel, in Unix milliseconds.

Delete the channel

Deletes the group channel.

DELETE https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Status: 200 OK
{}

List members

Returns the members of the channel.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/members
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
    "members": [
        {
            "nickname": "Terry",
            "last_seen_at": 1484036834043,
            "user_id": "terry5",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
            "is_online": false
        },
        {
            "nickname": "Bunny",
            "last_seen_at": 0,
            "user_id": "rabbit",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
            "is_online": true
        },
        {
            "nickname": "Lizzy",
            "last_seen_at": 1484111342965,
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
            "is_online": false
        },
        {
            "nickname": "Jack Brown",
            "last_seen_at": 0,
            "user_id": "jack2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_20_512px.png",
            "is_online": false
        }
    ],
    "next": ""
}
Property name Type Description
members[] list A list of the users who are members of the channel.
next string The token for the next chunk of results.

Check if member

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

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/members/{user_id}
Status: 200 OK
{
    "is_member": true
}
Property name Type Description
is_member boolean Whether the user is a member of the channel.

Invite members

Invites new users into the group channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/invite
Property name Type Description
user_ids[] list The string IDs of the users to be invited into the channel. The maximum number of users to be invited at once is 100.
Request body example
{
    "user_ids": ["megmeg", "panda", "kev@email.com"]
}

Returns a group channel representation.

Status: 200 OK
{
    "unread_message_count": 0,
    "max_length_message": -1,
    "is_distinct": false,
    "name": "Camp",
    "member_count": 4,
    "custom_type": "",
    "is_ephemeral": false,
    "created_at": 1484112314,
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "freeze": false, 
    "members": [
        {
            "state": "joined",
            "user_id": "panda",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 1484107339757,
            "nickname": "Kung Foo",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
        },
        {
            "state": "joined",
            "user_id": "rabbit",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 0,
            "nickname": "Bunny",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
        },
        {
            "state": "joined",
            "user_id": "megmeg",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 0,
            "nickname": "Megan",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
        },
        {
            "state": "joined",
            "user_id": "kev@email.com",
            "is_online": false,
            "is_active": true,
            "last_seen_at": 0,
            "nickname": "Kevin",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        }
    ],
    "last_message": {
        "created_at": 1540877348039,
        "mentioned_users": [],
        "mention_type": "users",
        "custom_type": "",
        "data": "",
        "message": "This is the last message of the channel.",
        "channel_url": "sendbird_group_channel_24896169_319372e8e023323529b29e7d41e935bb84e41f33",
        "type": "MESG",
        "message_id": 239092985,
        "updated_at": 0 
    },
    "unread_mention_count": 0,
    "is_public": false,
    "is_super": false,
    "joined_member_count": 4,
    "channel_url": "sendbird_group_channel_24896169_319372e8e023323529b29e7d41e935bb84e41f33",
    "channel": {
        ... # This key has been deprecated and only exists for backward compatibility.
    }
}

Hide the channel

Hides the group channel from a user’s group channel List. The channel stays hidden until new activity occurs within the channel (for example, someone sends a message), upon which the channel reappears in the user's list. This action is intended for users who want to temporarily remove a channel from their list, but not leave the channel (which would delete all past messages and stored data).

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/hide
Property name Type Description
user_id string The ID of the user who wishes to hide the channel from their list.
hide_previous_messages boolean Whether to hide existing channel messages when the hidden channel reappears due to a new inbound message. (Default: false)
Request example
{
    "user_id": "panda",
    "hide_previous_messages": "true"
}
Status: 200 OK
{}

Join the channel

Allows a user join the public group channel. Only permitted for public group channels where is_public with true

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/join
Property name Type Description
user_id string The user ID to join the channel.
Request body example
{
    "user_id": "panda"
}
Status: 200 OK
{}

Leave the channel

Makes user(s) leave the group channel.

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/leave
Property name Type Description
user_ids list The string IDs of the users to leave the channel.
Request body example
{
    "user_ids": ["megmeg", "panda", "kev@email.com"]
}
Status: 200 OK
{}

Freeze the channel

Freezes or unfreezes the channel.

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

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/freeze
Property name Type Description
freeze boolean Whether to freeze the channel.
Request body example
{
    "freeze": true
}

Returns an group channel representation.

Status: 200 OK
{
    "name": "Lizzy's stream",
    "participant_count": 0,
    "custom_type": "stream",
    "channel_url": "sendbird_group_channel_11694_20a8a958765129537e1e5532cf7fb18439804c57",
    "created_at": 1484036010,
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "freeze": true,
    "max_length_message": -1,
    "data": "",
    "operators": [
        {
            "nickname": "Lizzy",
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
    ]
}

Add operators

Adds operators to the channel. This API call is not available from SDK.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/operators
Property name Type Description
operator_ids[] list The string IDs of the users registered as channel operators. The operators should be invited for private group or joined for public group if they are not member of the group. The maximum number of operators for the channel is 100.
Request body example
{
    "operator_ids": ["megmeg", "panda", "kev@email.com"]
}
Status: 200 OK
{}

List operators

Returns the operators of the channel.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/operators
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=20
Status: 200 OK
{
    "operators": [
        {
            "nickname": "Terry",
            "last_seen_at": 1484036834043,
            "user_id": "terry5",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
            "metadata": {}
        },
        {
            "nickname": "Bunny",
            "last_seen_at": 0,
            "user_id": "rabbit",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
            "metadata": {}
        }
    ],
    "next": ""
}
Property name Type Description
operators[] list A list of the operators who are operators of the channel.
next string The token for the next chunk of results.

Remove operators

Removes operators from the channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/operators
Property name Type Description
operator_ids[] list The string IDs of the users to be removed from operators of the channel. The users in this list remain as the members of the channel after losing their operator roles.
Request body example
{
    "operator_ids": ["megmeg", "panda", "kev@email.com"]
}
Status: 200 OK
{}

Ban the user

Bans the target user from the channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/ban
Property name Type Description
user_id string The ID of the target user.
seconds (optional) int The ban duration. If set to -1, the user is banned permanently (10 years, technically). (Default: -1)
description (optional) string A description of the ban. The length is limited to 250 bytes.
Request body example
{
    "user_id": "terry5",
    "seconds": 60,
    "description": "rude behavior"
}
Status: 200 OK
{
    "description": "rude behavior",
    "start_at": 1484038674407,
    "user": {
        "nickname": "Terry",
        "user_id": "terry5",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    },
    "end_at": 1484038734407
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.

List banned users

Returns a list of the channel's banned users.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/ban
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. This value must be between 1 and 100. (Default: 10)
Request example
?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=2
Status: 200 OK
{
    "banned_list": [
        {
            "description": "aggressive language",
            "start_at": 1484095570557,
            "user": {
                "nickname": "Lizzy",
                "user_id": "elizabeth2",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
                "metadata":{}
            },
            "end_at": 1484095870557
        },
            {
            "description": "rude behavior",
            "start_at": 1484095557331,
            "user": {
                "nickname": "Kung Foo",
                "user_id": "panda",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
                "metadata":{}
            },
            "end_at": 1484095857331
        },
        {
            "description": "rude behavior",
            "start_at": 1484095551984,
            "user": {
                "nickname": "Terry",
                "user_id": "terry5",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
                "metadata":{}
            },
            "end_at": 1484095851984
        }
    ],
    "next": ""
}
Property name Type Description
banned_list[] list A list of bans.
banned_list[].description string A description of the ban.
banned_list[].user nested object The banned user.
banned_list[].start_at long The timestamp of when the ban began, in Unix milliseconds.
banned_list[].end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.
next string The token for the next chunk of results.

Update the ban

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

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}
Property name Type Description
seconds int The new ban duration. If set to -1, the user is banned permanently (10 years, technically).
description (optional) string An updated description of the ban. The length is limited to 250 bytes.
Request body example
{
    "description": "Additional rude behavior",
    "seconds": 3600
}
Status: 200 OK
{
    "description": "Additional rude behavior",
    "start_at": 1484096207311,
    "user": {
        "nickname": "Kung Foo",
        "user_id": "panda",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    "end_at": 1484099852886
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.

View the ban

Returns details of a ban imposed on the user.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}
Status: 200 OK
{
    "description": "Additional rude behavior",
    "start_at": 1484096207311,
    "user": {
        "nickname": "Kung Foo",
        "user_id": "panda",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    "end_at": 1484099951995
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.

Unban the user

Unbans the user from the channel.

DELETE https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/ban/{banned_user_id}
Status: 200 OK
{}

Mute the user

Mutes the target user in the channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/mute
Property name Type Description
user_id string The ID of the target user.
Request body example
{
    "user_id": "panda"
}
Status: 200 OK
{}

List muted users

Returns a list of the channel's muted users.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/mute
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=2
Status: 200 OK
{
    "muted_list": [
        {
            "nickname": "Lizzy",
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        {
            "nickname": "Terry",
            "user_id": "terry5",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        }
    ],
    "next": "a3YUS1E8Q1FMFEVfWlVZEGJyGQ~~"
}
Property name Type Description
muted_list[] list A list of the muted users
next string The token for the next chunk of results.

View the mute

Returns whether the user is muted in the channel.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/mute/{muted_user_id}
Status: 200 OK
{
    "is_muted": boolean
}
Property name Type Description
is_muted boolean Whether the user is muted in the channel.

Unmute the user

Unmutes the user within the channel.

DELETE https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/mute/{muted_user_id}
Status: 200 OK
{}