Home
/
Chat
/
Platform API

Open channel

An open channel is a Twitch-style public chat where users can easily join without permission. Sendbird Chat SDK now supports two operation systems for open channels, which are classic and dynamic partitioning. These two systems offer the same features and functions, except that dynamic partitioning allows open channels to accommodate a massive number of users.

Open channels can be used in short-lived live events, such as streaming, news-feed type messaging to massive audience, or events that don't require a permanent membership.

Note: To learn about differences between open channels and group channels, see Channel types.


Classic vs. Dynamic partitioning

Classic open channels are the original open channels Sendbird has been providing, and a single classic open channel can handle up to 1,000 participants.

Note: Sendbird applications created before December 15, 2020, are using classic open channels.

On the other hand, dynamic partitioning open channels are designed to accommodate an even larger number of users using a set number of subchannels, starting from 2,000 to 20,000 participants for shared regions and up to 60,000 participants for dedicated regions. This new system, called dynamic partitioning, enables flexible scaling of open channels by creating or merging subchannels within the open channels and evenly allocating participants among the subchannels while providing a seamless and well-paced chat experience to all users.

Note: The classic open channels will be deprecated by the end of March 2021 but the classic channels created before the deprecation will remain and function the same way. Meanwhile, all Chat SDK users will be automatically migrated to the new dynamic partitioning system when the deprecation takes place. If you wish to convert to dynamic partitioning open channels beforehand, contact our support team.


How dynamic partitioning works

Subchannel type

Subchannels are a mini channel that is created within an open channel. Dynamic partitioning offers two types of subchannels, which include Single and Multiple. An open channel of the Single subchannel type is allowed to have only one single subchannel while an open channel of the Multiple subchannel type can create several subchannels depending on the number of participants joining the open channel. Each subchannel can accommodate an equal share of participants and whenever one subchannel reaches the allocation_ratio, another subchannel is created. Let's say that your open channel can accommodate 20,000 participants and create ten subchannels, which is the default value. In that case, each subchannel will take a group of 2,000 participants.

Note: You can select the subchannel type in the Sendbird Dashboard.

User allocation

An open channel with dynamic partitioning can scale up and down by automatically creating subchannels based on the number of participants joining the open channel. The first subchannel is created when an open channel is created. When a user joins the open channel, Sendbird server allocates the user to the first subchannel. Subsequent users who participate in the open channel will continue to be allocated to the first subchannel until the number of participants in the subchannel reaches the allocation_ratio, the rate of participants in one subchannel that can prompt the creation of a new subchannel.

When the first subchannel reaches the allocation_ratio, Sendbird server creates a second subchannel and starts to allocate incoming users to the new subchannel. This process is repeated until the total number of participants in the open channel reach the max_total_participants.

When all the existing subchannels hit the allocation_ratio, Sendbird server starts to allocate incoming users in a round-robin fashion. This means that newcomers who join the open channel after all the subchannels reach the allocation_ratio will be allocated to each subchannel one at a time, not all in one subchannel. The round-robin allocation is continued until all subchannels reach their full capacity set by the max_participants_per_subchannel.

If some of the subchannels falls below the allocation_ratio, Sendbird server allocates a newly joined user to the subchannel that has the lowest number of participants at the time of the user’s entrance.

Note: The max_total_participants and max_participants_per_subchannel attributes have fixed values. To confirm their values, contact our support.

User deallocation

Subchannels have a lifetime. The subchannel_min_lifetime indicates how long a subchannel can last when its participant numbers are below a certain level. This time limit is used for user deallocation. If the ratio of participants in a subchannel to the max_participants_per_subchannel falls below the deallocation_ratio and remains so for the subchannel_min_lifetime, the subchannel is merged into a subchannel that has the lowest number of users at that time. When subchannels are merged, the value of the max_participants_per_subchannel is ignored.

Subchannel view

As for an open channel with dynamic partitioning, participants in one subchannel can't interact with those in other subchannels. However, they all share the same channel theme and live streaming content, which makes all subchannels seemingly identical. For example, participants in Subchannel #1 can’t see the conversation taking place in Subchannel #2. However, the participants in both subchannels still enjoy their chat in the same environment with the identical channel UI and the same content broadcasted to all subchannels. Given its nature, an open channel with dynamic partitioning is suitable for occasions that demand a full-scale chat, such as a gaming community and a live streaming event.

Operators in a global channel

A global subchannel is a special subchannel for channel operators that allows them to receive every single message from all subchannels. While participants in one subchannel can read only the messages exchanged within the subchannel, operators can read all the messages created in every subchannel. In addition, the operators in the global channel are not counted towards the max_total_participants and max_participants_per_subchannel properties.

Note: If the subchannel type is set to Multiple, an admin message sent by operators is sent to all subchannels.

Channel configuration

The following table lists the attributes that can be configured for dynamic partitioning open channels.

Note: To adjust the value of these attributes, contact our support.

List of attributes

Property nameTypeDescription

allocation_ratio

float

The ratio of the number of participants to the max_participants_per_subchannel. This figure is used to decide when to create a new subchannel and allocate new incoming users to the new channel. When the most recently created subchannel reaches the allocation_ratio, Sendbird server creates another subchannel and sends newly joined users to the new subchannel. This process is repeated before the total number of participants in the open channel reaches the max_total_participants. (Default: 0.6, indicating 60%)

deallocation_ratio

float

The ratio of the number of participants to the max_participant_per_subchannel. Sendbird server uses this to decide when to initiate the deallocation of participants by merging subchannels. If a subchannel reaches the deallocation_ratio and continues to stay below the ratio for the time period set by the subchannel_min_lifetime, the subchannel will then be absorbed into another subchannel with the lowest number of participants. When deallocation takes place, the value set for max_participants_per_subchannel is ignored. (Default: 0.05, indicating 5%)

stickiness_duration_to_subchannel

int

The set time period that allows a participant who left a subchannel to come back to the same subchannel, in seconds. If a participant returns to the open channel within the stickiness_duration_to_subchannel time, the user can re-enter the same subchannel that they left.
If the user returns after the subchannel they left has already reached the max_participants_per_subchannel, the user will be allocated to a random subchannel even when they re-enter within the stickiness_duration_to_subchannel. (Default: 1,800, indicating 60 seconds x 60 minutes x 3 hours)

max_recent_messages_count

int

The number of recent messages to keep in each subchannel. Subchannel messages are stored only for the set time period for subchannel_messages_lifetime. (Default: 30 per subchannel)

subchannel_messages_lifetime

int

The set time period for messages to be stored, in days. Because all messages in a subchannel can remain there for the time set by this property, a participant can retrieve previous messages in their subchannel within this time window. Whenever a new message is sent within the subchannel_messages_lifetime, the count is reset. (Default: 7 days)

subchannel_min_lifetime

int

The set time period for a subchannel to last after it reaches the deallocation_ratio. When the ratio of participants in a subchannel to the max_participants_per_subchannel falls below the value set by deallocation_ratio and remains that way for the time set by this property, and Sendbird server begins deallocation of participants. (Default: 600, indicating 60 seconds x 10 minutes)


Resource representation

The following table lists the common properties shared by both classic and dynamic partitioning open channels.

Property nameTypeDescription

name

string

The channel topic, or the name of the channel.

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 a long description of the channel or JSON formatted string.

is_ephemeral

boolean

Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history.

participant_count

int

The current number of participants in the channel. Once the number exceeds 500, this count is sent according to the following two rules.

- Time-based: the participant count is sent every five minutes.
- Number-based: besides the time-based counts, an additional count is sent whenever the participant number increases by an increment of 10, 100, and 1,000. For example, the count is sent when the participant number reaches 510, 520, 530, and so on. When the participant number exceeds 1,000, the count is sent for 1,100, 1,200, 1,300, and so on. When it exceeds 10,000, the count is sent for 11,000, 12,000, 13,000, and so on.

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.

created_at

long

The timestamp of when the channel was created, in Unix seconds format.

operators[]

list

The list of users registered as operators of the channel. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

* Operators cannot view messages that have been moderated by the domain filter or profanity filter. Only the sender will be notified that the message has been blocked.

freeze

boolean

Indicates whether the channel is currently frozen. A value of true indicates that normal participants can't chat within the channel but the operators can.

is_dynamic_partitioned

boolean

Indicates whether the channel is an open channel with dynamic partitioning or not. If the value of this property is true, the properties below show the detail configuration of the open channel with dynamic partitioning. (Default: false)

* For the new Sendbird applications created after December 15, 2020, this property will be automatically set to true.


Actions

  • API endpoints are relative to the base URL allocated to the application. In this page, the /open_channels endpoint refers to https://api-{application_id}.sendbird.com/v3/open_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}.

List of actions for managing channels

ActionHTTP request

List channels

GET /open_channels
Retrieves a list of open channels. You can query the list using various parameters.

View a channel

GET /open_channels/{channel_url}
Retrieves information on an open channel.

Create a channel

POST /open_channels
Creates an open channel.

Update a channel

PUT /open_channels/{channel_url}
Updates information on a specific open channel.

List participants

GET /open_channels/{channel_url}/participants
Retrieves a list of the participants in a specific open channel. A participant refers to a user who has entered the open channel and is currently online.

Freeze a channel

PUT /open_channels/{channel_url}/freeze
Freezes a specific open channel.

Delete a channel

DELETE /open_channels/{channel_url}
Deletes a specific open channel.

List of actions for channel operators

ActionHTTP request

List operators

GET /open_channels/{channel_url}/operators
Retrieves a list of the operators of a specific open channel.

Register operators

POST /open_channels/{channel_url}/operators
Registers a list of one or more users to be assigned as operators of a specific open channel.

Cancel the registration of operators

DELETE /open_channels/{channel_url}/operators
Cancels the registration of operators from a specific open channel.

List of actions for channel moderation

ActionHTTP request

List banned users

GET /open_channels/{channel_url}/ban
Retrieves a list of the banned users from a specific open channel.

View a ban

GET /open_channels/{channel_url}/ban/{banned_user_id}
Retrieves details of a ban imposed on the user.

Ban a user

POST /open_channels/{channel_url}/ban
Bans a user from a specific open channel.

Update a ban

PUT /open_channels/{channel_url}/ban/{banned_user_id}
Updates details of a ban imposed on the user. You can change the length of a ban with this action, and also provide an updated description.

Unban a user

DELETE /open_channels/{channel_url}/ban/{banned_user_id}
Unbans the user.

List muted users

GET /open_channels/{channel_url}/mute
Retrieves a list of the muted users in a specific open channel.

View a mute

GET /open_channels/{channel_url}/mute/{muted_user_id}
Retrieves details of a mute imposed on the user.

Mute a user

POST /open_channels/{channel_url}/mute
Mutes a user in a specific open channel.

Unmute a user

DELETE /open_channels/{channel_url}/mute/{muted_user_id}
Unmutes the user.


List channels

Retrieves a list of open channels. You can query the list using various parameters.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

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)

custom_types

string

Specifies a comma-separated string of one or more custom types to filter the open 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.

name_contains

string

Searches for open channels containing the specified value in their channel name. Note that this parameter is case-insensitive. Urlencoding the value is recommended.

url_contains

string

Searches for open channels containing the specified value in their channel URL. Urlencoding the value is recommended.

show_frozen

boolean

Determines whether to include frozen channels in the response. Frozen channels are channels that only channel operators are allowed to send messages. (Default: true)

show_metadata

boolean

Determines whether to include channel metadata in the response. (Default: false)

custom_type

string

(Deprecated) Searches channels whose custom_type matches the given value. If not specified, all channels are returned. The string passed here must be urlencoded.

Query string example
Light Color Skin
Copy
?token=&limit=5&custom_types=live&name_contains=streaming

Response

If successful, this action returns a list of open channel resources that match the query parameters in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "channels": [
        {
            "name": "LA Lakers vs. Miami Heat Basketball Live streaming today!",
            "channel_url": "monday_channel7_at_9_pm",
            "custom_type": "live",
            "is_ephemeral": false,
            "participant_count": 1023,
            "max_length_message": 5000,
            "created_at": 1484789122,
            "cover_url": "https://sendbird.com/main/img/cover/cover_12.jpg",
            "data": "{event_trigger:100,500,1000,2000}",
            "operators": [
                {
                    "user_id": "Daniel",
                    "nickname": "Smileguy",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
                }
            ],
            "freeze": false,
            "metadata": {
                "background_image": "https://sendbird.com/main/img/bg/theme_013.png",
                "text_size": "large"
            }
        },
        ... # More open channels
    ],
    "next": "XYZEK1VVQVErEUBXWFNeFp3Q2FkFVA~~"
}

List of response properties

Property nameTypeDescription

channels[]

list

A list of open 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 specific open channel.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_url

string

Specifies the URL of the channel to retrieve.

Response

If successful, this action returns an open channel resource in the response body.


Create a channel

Creates an open channel.

Note: Classic open channels created before the deprecation date of March 2021 will maintain their original form and functions. However, new applications created after December 15, 2020, will be able to create dynamic partitioning open channels only.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/open_channels

Request body

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

Properties
OptionalTypeDescription

name

string

Specifies the channel topic, or the name of the channel. The length is limited to 191 characters. (Default: open 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. The length is limited to 2,048 characters.

cover_file

file

Uploads a file for the channel cover image.

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_ephemeral

boolean

Determines whether to preserve the messages in the channel for the purpose of retrieving chat history or not. It set to true, the messages in the channel are not saved in the Sendbird database and the chat history can't be retrieved. (Default: false)

is_dynamic_partitioned

boolean

Determines whether the channel is an open channel with dynamic partitioning or not. If the value of this property is true, the open channel can create several subchannels in order to accommodate a massive number of users. (Default: false)

* For the new Sendbird applications created after December 15, 2020, this property will be automatically set to true.

operator_ids[]

array

Specifies an array of one or more user IDs to register as operators of the channel. The maximum allowed number of operators per channel is 100. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

* Operators cannot view messages that have been moderated by the domain filter or profanity filter. Only the sender will be notified that the message has been blocked.

operators[]

array

(Deprecated) Specifies the string IDs of the users registered as channel operators. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

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": "Live streaming show on channel 5!",
    "channel_url": "monday_channel_5_at_10_pm",
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "data": "{event_trigger:100,500,1000,2000}",
    "operator_ids": ["Alek", "Leslie"],
    "custom_type": "Live"
}

Response

If successful, this action returns an open channel resource in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "name": "Live streaming show on channel 5!",
    "channel_url": "monday_channel5_at_10_pm",
    "custom_type": "live",
    "is_ephemeral": false,
    "participant_count": 0,
    "max_length_message": 5000,
    "created_at": 1484787758,
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "data": "{event_trigger:100,500,1000,2000}",
    "operators": [
        {
            "user_id": "Alek",
            "nickname": "Alexander the Great",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        },
        {
            "user_id": "Leslie",
            "nickname": "Crystal",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_27_512px.png"
        }
    ],
    "freeze": false
}

Update a channel

Updates information on an open channel.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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
OptionalTypeDescription

name

string

Specifies the channel topic, or the name of the channel. The length is limited to 191 characters.

cover_url

string

Specifies the URL of the cover image. The length is limited to 2,048 characters.

cover_file

file

Uploads the file for the channel cover image.

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.

operator_ids[]

array

Specifies an array of one or more user IDs to register as operators of the channel. The maximum allowed number of operators per channel is 100. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

* Operators cannot view messages that have been moderated by the domain filter or profanity filter. Only the sender will be notified that the message has been blocked.

operators[]

array

(Deprecated) Specifies the string IDs of the users registered as channel operators. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

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 an updated open channel resource in the response body.


List participants

Retrieves a list of the participants of an open channel. A participant refers to a user who has entered the open channel and is currently online.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/participants

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_url

string

Specifies the URL of the channel to retrieve a list of participants in.

OptionalTypeDescription

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 user resources that are participating in the open channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "participants": [
        {
            "user_id": "Carlos",
            "nickname": "Wholla",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_52_512px.png",
            "last_seen_at": 1542356223387,
            "is_muted": false,
            "is_online": true
        },
        ... # More participants
    ],
    "next": "YnQSRDpSRl1AEE1WXlVaF2R3"
}

List of response properties

Property nameTypeDescription

participants[]

list

A list of users who are participating in the open channel.

next

string

The value for the token parameter to retrieve the next page in the result set.


Freeze a channel

Freezes or unfreezes an open 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/open_channels/{channel_url}/freeze

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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
RequiredTypeDescription

freeze

boolean

Determines whether to freeze the channel. (Default: true)

Response

If successful, this action returns an open channel resource in the response body.


Delete a channel

Deletes an open channel.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_url

string

Specifies the URL of the channel to delete.

Response

If successful, this action returns an empty response body.


List banned users

Retrieves a list of banned users from a specific open channel.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_url

string

Specifies the URL of the channel where to retrieve a list of banned users.

OptionalTypeDescription

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 0 and 100. (Default: 10)

show_total_ban_count

boolean

Determines whether to include the number of all banned users in the response. (Default: false)

Query string example
Light Color Skin
Copy
?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=5&show_total_ban_count=true

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": "Matthew",
                "nickname": "Mooch",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_47_512px.png",
                "metadata": {
                    "location": "San Diego",
                    "marriage": "N"
                }
            },
            "start_at": 1543211469000,
            "end_at": 1543211529000,
            "description": "Too much talking"
        },
        ... # More banned users
    ],
    "total_ban_count" : 10,
    "next": "KQnRP2aZR1nRAE1WXlVaR4w6",
}

List of response properties

Property nameTypeDescription

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.

total_ban_count

int

The number of all banned users.

next

string

The value for the token parameter to retrieve the next page in the result set.


List operators

Retrieves a list of operators of an open channel.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_url

string

Specifies the URL of the channel to retrieve a list of operators.

OptionalTypeDescription

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": "Katherine",
            "nickname": "Kathie",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_176_512px.png",
            "metadata": {
                "location": "Chicago",
                "marriage": "N"
            }
        },
        ... # More operators
    ],
    "next": "aKV1e3deQVEZEuBRWFNeFp3Q2Fk3Tr~~"
}

List of response properties

Property nameTypeDescription

operators[]

list

A list of users registered as 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 an open channel.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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
RequiredTypeDescription

operator_ids[]

array

Specifies an array of one or more IDs of users to register as operators of the channel. The maximum allowed number of operators per channel is 100.

Request body example
Light Color Skin
Copy
{
    "operator_ids": ["Julia", "Katherine", "Cindy"]
}

Response

If successful, this action returns an empty response body.


Cancel the registration of operators

Cancels the registration of operators from an open channel but leave them as participants.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/operators

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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).

OptionalTypeDescription

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=Katherine,Cindy

Response

If successful, this action returns an empty response body.


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/open_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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 an open channel. A banned user is immediately expelled from a channel and allowed to participate in the channel again after a set time period.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_url

string

Specifies the URL of the channel where to ban the specified user.

Request body

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

Properties
RequiredTypeDescription

user_id

string

Specifies the ID of the user to ban.

OptionalTypeDescription

agent_id

string

Specifies the ID of the operator (agent) 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": "Matthew",
    "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": "Matthew",
        "nickname": "Mooch",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_47_512px.png",
        "metadata": {
            "location": "San Diego",
            "marriage": "N"
        }
    },
    "start_at": 1543211469000,
    "end_at": 1543211529000,
    "description": "Too much talking"
}

List of response properties

Property nameTypeDescription

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 a ban with this action, and also provide an updated description.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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
OptionalTypeDescription

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 updated information on a ban in the response body.


Unban a user

Unbans a user from an open channel.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_url

string

Specifies the URL of the target channel.

banned_user_id

string

Specifies the ID of the banned user to unban.

Response

If successful, this action returns an empty response body.


List muted users

Retrieves a list of muted users in the channel.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_url

string

Specifies the URL of the channel to retrieve a list of muted users.

OptionalTypeDescription

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 0 to 100, inclusive. (Default: 10)

show_total_mute_count

boolean

Determines whether to include the number of all muted users in the response. (Default: false)

Query string example
Light Color Skin
Copy
?token=&limit=5&show_total_mute_count=true

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "muted_list": [
        {
            "user_id": "Jeremy",
            "nickname": "Bishop",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_48_512px.png",
            "metadata": {
                "location": "Tucson",
                "marriage": "N"
            },
            "remaining_duration": -1,
            "end_at": -1,
            "description": "too many abnormal messages in the channel"
        },
        {
            "user_id": "Oliver",
            "nickname": "Han Solo",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_65_512px.png",
            "metadata": {
                "location": "Fort Worth",
                "marriage": "N"
            },
            "remaining_duration": 21253000,
            "end_at": 1542722786000,
            "description": "relationless messages"
        },
        ... # More muted users
    ],
    "total_mute_count" : 10,
    "next": "a3YUS1E8Q1FMFEVfWlVZEGJyGQ~~"
}

List of response properties

Property nameTypeDescription

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.

total_mute_count

int

The number of all muted users.


View a mute

Checks if a user is muted in an open channel.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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": "too many messages"
}

List of response properties

Property nameTypeDescription

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 the 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/open_channels/{channel_url}/mute

Request body

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

Properties
RequiredTypeDescription

user_id

string

Specifies the ID of the target user to mute.

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 an open channel resource in the response body.


Unmute a user

Unmutes a user from an open channel.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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.