Platform API
Open Channel

Open Channel

An open channel is basically a public chat and it can handle a large number of participants online. In this channel type, anyone can enter and participate in the chat without permission. A single open channel can accomodate up to 1,000, simultaneous users like Twitch-style public chat. This maximum number of an open channel's participants can increase per request.

Resource representation

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.

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 messages allowed to be sent within the channel. A value of -1 indicates that the length is unlimited.

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, select the application, open the Overview, and then check the App credentials > App 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
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.

Moderation for channels
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.

Parameters
OptionalTypeDescription

token

string

Specifies a 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 open channels with those custom types. If this parameter is 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. It is recommended that the value is urlencoded.

url_contains

string

Searches for open channels containing the specified value in their channel URL. It is recommended that the value is urlencoded.

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": -1,
            "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 nameTypeDescription

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
RequiredTypeDescription

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
OptionalTypeDescription

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. (Default: "")

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 the IDs of the users to register as operators to the channel. Operators can delete any messages, and also view all messages in the channel without any filtering or throttling. The maximum number of operators for the 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": -1,
    "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
RequiredTypeDescription

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 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 the IDs of the users to register 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 that updating this field 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. They can also view all messages in the channel without any filtering or throttling. Note that updating this field 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.

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
RequiredTypeDescription

channel_url

string

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

OptionalTypeDescription

token

string

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

Parameters
RequiredTypeDescription

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

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

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
RequiredTypeDescription

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

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
RequiredTypeDescription

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

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


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
RequiredTypeDescription

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

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.