Open Channel

Open Channel is a public chat by nature and it can handle a large number of participation online. In this channel type, anyone can enter and participate in the chat without permission. A single channel can handle up to one thousand, simultaneous users like Twitch-style public chat. This default number of participants can increase per request.

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.
cover_file file The file of the cover image.
data string Additional data that you can store within a channel.
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.
custom_type string A field used to further subclassify the channel.
participants list A list of users who are participating in the open channel.
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. If set to -1, the length is unlimited.
created_at long The time in which the channel was created. The value is in Unix seconds format.
freeze boolean Whether the channel is currently frozen. If true, then ordinary participants cann't chat within the channel.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /open_channels endpoint refers to https://{region_identifier}.sendbird.com/v3/open_channels.

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

  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Create a channel POST /open_channels Creates an open channel.
List channels GET /open_channels Returns a list of open channels.
Update the channel PUT /open_channels/{channel_url} Updates the channel’s information.
View the channel GET /open_channels/{channel_url} Returns the channel’s information.
Delete the channel DELETE /open_channels/{channel_url} Deletes the open channel.
List participants GET /open_channels/{channel_url}/participants Returns the participants of the open channel.
Freeze a channel PUT /open_channels/{channel_url}/freeze Freezes the open channel.
Ban a user POST /open_channels/{channel_url}/ban Bans a user from the open channel.
List banned users GET /open_channels/{channel_url}/ban Returns a list of the banned users in the channel.
Update the ban PUT /open_channels/{channel_url}/ban/{banned_user_id} Updates details of a ban imposed on the user.
View the ban GET /open_channels/{channel_url}/ban/{banned_user_id} Returns details of a ban imposed on the user.
Unban the user DELETE /open_channels/{channel_url}/ban/{banned_user_id} Unbans the user.
Mute a user POST /open_channels/{channel_url}/mute Mutes a user.
List muted users GET /open_channels/{channel_url}/mute Returns a list of the muted users in the channel.
View the mute GET /open_channels/{channel_url}/mute/{muted_user_id} Returns details of a mute imposed on the user.
Unmute the user DELETE /open_channels/{channel_url}/mute/{muted_user_id} Unmutes the user.

Create a channel

Creates an open channel.

POST https://{region_identifier}.sendbird.com/v3/open_channels
Property name Type Description
name (optional) string The channel topic, or the name of the channel. The length is limited to 1,024 bytes. (Default: Open Channel)
channel_url (optional) string The URL of the channel. Only numbers, characters, and underscores are allowed. The length is 4 to 100 bytes, inclusive. If not specified, a URL is automatically generated.
cover_url (optional) file The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the channel cover image.
custom_type (optional) string A field you can use to further subclassify your channels. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within a channel.
operator_ids[] (optional) list 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. The maximum number of operators for the channel is 100.
operators (optional) list (Deprecated) 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
{
    "name": "Main Lobby",
    "channel_url": "open_channel_1",
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "data": "",
    "operator_ids": ["terry5", "elizabeth2"],
    "custom_type": "lobby"
}

Returns an open channel representation.

Status: 200 OK
{
    "name": "Main Lobby",
    "participant_count": 0,
    "custom_type": "lobby",
    "is_ephemeral": false,
    "channel_url": "open_channel_1",
    "created_at": 1484787758,
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "freeze": false,
    "max_length_message": -1,
    "data": "",
    "operators": [
        {
            "nickname": "Terry",
            "user_id": "terry5",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        },
        {
            "nickname": "Lizzy",
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
    ]
}

List channels

Returns a list of open channels. You can query the list based on various parameters.

GET https://{region_identifier}.sendbird.com/v3/open_channels
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
custom_types string Search for channels with the specified custom types. The string passed here must be urlencoded, with multiple custom types separated by commas. (for example, url_endcoded_custom_type_1, url_encoded_custom_type_2). If this field is not specified, all channels are returned, regardless of their custom type.
custom_type string (Deprecated) Returns channels whose custom_type matches the given value. If not specified, all channels are returned. The string passed here must be urlencoded.
Request example
?token=&limit=2&custom_types=lobby,room

Returns a list of open channels.

Status: 200 OK
{
    "channels": [
        {
            "name": "Lobby1",
            "participant_count": 0,
            "custom_type": "lobby",
            "channel_url": "sendbird_open_channel_11694_c0985202490b5a5064f5dc736ae08be862393699",
            "created_at": 1484094126,
            "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
            "freeze": false,
            "max_length_message": -1,
            "data": "This room is a central lobby.",
            "operators": [
                {
                    "nickname": "Bunny",
                    "user_id": "rabbit",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
                },
                {
                    "nickname": "Lizzy",
                    "user_id": "elizabeth2",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
                }
            ]
        },
        {
            "name": "Room1",
            "participant_count": 0,
            "custom_type": "room",
            "channel_url": "sendbird_open_channel_11694_cb2b08de97bea4de5a3eaa69ad5bde5143e057d9",
            "created_at": 1484035890,
            "cover_url": "https://sendbird.com/main/img/cover/cover_06.jpg",
            "freeze": false,
            "max_length_message": -1,
            "data": "",
            "operators": [
                {
                    "nickname": "Terry",
                    "user_id": "terry5",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
                },
                {
                    "nickname": "Kung Foo",
                    "user_id": "panda",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
                }
            ]
        }
    ],
    "next": ""
}
Property name Type Description
channels[] list A list of open channels that match the specifed optional parameters.
next string The token for the next chunk of results.

Update the channel

Updates the channel's information.

PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Property name Type Description
name (optional) string The channel topic, or the name of the channel. The length is limited to 1,024 bytes.
cover_url (optional) file The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the channel cover image.
custom_type (optional) string A field you can use to further subclassify your channels. The length is limited to 128 bytes.
data (optional) string Additional data that you can store within a channel.
operator_ids[] (optional) list 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 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 (optional) list (Deprecated) 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 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.

Request body example
{
    "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
    "operator_ids": ["elizabeth2", "rabbit"]
}

Returns an open channel representation.

Status: 200 OK
{
    "name": "Lobby3",
    "participant_count": 0,
    "custom_type": "lobby",
    "channel_url": "sendbird_open_channel_11694_c0985202490b5a5064f5dc736ae08be862393699",
    "created_at": 1484094126,
    "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
    "freeze": false,
    "max_length_message": -1,
    "data": "This room is a central lobby.",
    "operators": [
        {
            "nickname": "Bunny",
            "user_id": "rabbit",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        {
            "nickname": "Lizzy",
            "user_id": "elizabeth2",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
    ]
}

View the channel

Returns the channel’s information.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Parameter name Type Description
participants boolean If true, a list of users active participants in the channel is included in the response body. (Default: false)
Request example
?participants=true

Returns an open channel representation.

Status: 200 OK
{
    "name": "Lobby",
    "participant_count": 2,
    "custom_type": "lobby",
    "channel_url": "sendbird_open_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
    "created_at": 1483606460,
    "cover_url": "https://sendbird.com/main/img/cover/cover_09.jpg",
    "freeze": false,
    "participants": [
        {
            "user_id": "terry5",
            "is_muted": false,
            "is_online": true,
            "last_seen_at": 0,
            "nickname": "Terry",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        },
        {
            "user_id": "turtle",
            "is_muted": false,
            "is_online": true,
            "last_seen_at": 0,
            "nickname": "Ninja",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png"
        }
    ],
    "max_length_message": -1,
    "data": "",
    "operators": []
}

Delete the channel

Deletes the open channel.

DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Response: 200 OK
{}

List participants

Returns the participants of the open channel. The participant are users who have joined the open channel and are currently online.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/participants
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=2
Status: 200 OK
{
    "participants": [
        {
            "user_id": "rabbit",
            "is_muted": false,
            "is_online": true,
            "last_seen_at": 0,
            "nickname": "Bunny",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_15_512px.png"
        },
        {
            "user_id": "panda",
            "is_muted": false,
            "is_online": true,
            "last_seen_at": 0,
            "nickname": "kungfoo",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
    ],
    "next": "YnQSRDpSRl1AEE1WXlVaF2R3"
}
Property name Type Description
participants[] list A list of users who are participating in the open channel.
next int The token for the next chunk of results.

Freeze a channel

Freezes or unfreezes the channel.

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

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

Returns an open channel representation.

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

Ban a user

Bans the target user from the channel.

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

List banned users

Returns a list of the channel's banned users.

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

Update the ban

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

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

View the ban

Returns details of a ban imposed on the user.

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

Unban the user

Unbans the user from the channel.

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

Mute a user

Mutes a user in the channel.

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

Returns an open channel representation.

Status: 200 OK
{
    "name": "Unfriendly Chat",
    "participant_count": 0,
    "custom_type": "",
    "channel_url": "sendbird_open_channel_11694_49b4bdde3135226a859fcb61996b11b8aa2ca2b0",
    "created_at": 1484036092,
    "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
    "freeze": false,
    "max_length_message": -1,
    "data": "",
    "operators": []
}

List muted users

Returns a list of the channel's muted users.

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

View the mute

Returns whether the user is muted in the channel.

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

Unmute the user

Unmutes the user within the channel.

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