Open Channel | Platform API Chat SDK Documentation

Platform API

Open Channel

An open channel is a public chat by nature that can handle a large number of online users. A single open channel can accommodate up to 1,000 simultaneous users in a Twitch-style public chat, and anyone can easily participate without permission. This maximum number of participants can increase per request.

Resource representation

Property name	Type	Description
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.
data	string	Additional data that you can store for the channel.
is_ephemeral	boolean	Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history.
participant_count	int	The number of participants in the channel.
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. They also view all messages in the channel without any filtering or throttling.
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.

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 Credentials > Application ID, API request URL.

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

Managing channels

Action	HTTP 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.

Moderation for channels

Action	HTTP 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.

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)
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. 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.
~~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,
            "created_at": 1484789122,
            "cover_url": "https://sendbird.com/main/img/cover/cover_12.jpg",
            "max_length_message": 500,
            "participant_count": 1023,
            "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
        },
        ... # more open channels    
    ],
    "next": "XYZEK1VVQVErEUBXWFNeFp3Q2FkFVA~~"
}

Property name	Type	Description
channels[]	list	A list of open channels that match the specifed 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.

Parameters

Required	Type	Description
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.

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

Optional	Type	Description
name	string	Specifies the channel topic, or the name of the channel. The length is limited to 1,024 bytes. (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 bytes, 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 bytes.
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 bytes.
data	string	Specifies additional data that you can store for the channel.
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)
operator_ids[]	array	Specifies an array of one or more user IDs to register as operators of the channel. Operators can delete any messages in the channel, and can also view all messages without any filtering or throttling. The maximum number of operators allowed per channel is 100.
~~operators[]~~	array	*(Deprecated)* Specifies the string IDs of the users registered as channel operators. Operators can delete any messages in the channel. They can also view all messages in the channel without any filtering or throttling.

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 like the following.

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,
    "created_at": 1484787758,
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "max_length_message": 500,
    "participant_count": 538,
    "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.

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 channel topic, or the name of the channel. The length is limited to 1,024 bytes.
cover_url	string	Specifies the URL of the cover image. The length is limited to 2,048 bytes.
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 bytes.
data	string	Specifies additional data that you can store within a channel.
operator_ids[]	array	Specifies an array of one or more user IDs to register as operators of the channel. Operators can delete any messages in the channel, and can also view all messages without any filtering or throttling. * Updating this property overwrites previous operators of the channel. If you want to add an operator, include all previous operators as well as the user to be added.
~~operators[]~~	array	*(Deprecated)* Specifies the IDs of the users registered as channel operators. Operators* can delete any messages in the channel, and can also view all messages in the channel without any filtering or throttling.*

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

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

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 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"
}

Property name	Type	Description
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.

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

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

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": "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 bans 
    ],
    "next": "KQnRP2aZR1nRAE1WXlVaR4w6"
}

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 constains 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/open_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 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.

Parameters

Required	Type	Description
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

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

Optional	Type	Description
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 is banned permanently (10 years, technically). (Default: -1)
description	string	Specifies a reason for the banning. The length is limited to 250 bytes.

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"
}

Property name	Type	Description
user	nested object	The user resource which constains 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.

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 is banned permanently (10 years, technically).
description	string	Specifies a new reason for the banning to update. The length is limited to 250 bytes.

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

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

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 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
    ],
    "next": "a3YUS1E8Q1FMFEVfWlVZEGJyGQ~~"
}

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

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

Required	Type	Description
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 is 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.

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.

Channel Types

Group Channel

Contents

List channels View a channel Create a channel Update a channel List participants Freeze a channel Delete a channel List banned users View a ban Ban a user Update a ban Unban a user List muted users View a mute Mute a user Unmute a user