## 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 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 messages allowed to be sent within the channel. If set to **-1**, the length is unlimited.| |created_at|long|The timestamp of when the channel was created, in [Unix seconds](/platform/misc#3_timestamps) format.| |operators[]|list|The list of [users](/platform/user#4_resource_representation) 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 allocated [base URL](/platform/quick_start#3_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 the `region_identifier` for your SendBird application, sign in to the [SendBird Dashboard](https://dashboard.sendbird.com), select the application, open the **Overview**, and see the **App Credentials > API URL**. * It's recommended that the parameter values in API URLs are [urlencoded](/platform/quick_start#3_url_encoding), such as `{user_id}` and `{channel_url}`.

|Action|HTTP request| |---|---| |[List channels](#3_list_channels)|`GET` **/open_channels**
Retrieves a list of open channels. You can query the list using various parameters.| |[View a channel](#3_view_a_channel)|`GET` **/open_channels/{channel_url}**
Retrieves information on an open channel.| |[Create a channel](#3_create_a_channel)|`POST` **/open_channels**
Creates an open channel.| |[Update a channel](#3_update_a_channel)|`PUT` **/open_channels/{channel_url}**
Updates information on a specific open channel.| |[List participants](#3_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](#3_freeze_a_channel)|`PUT` **/open_channels/{channel_url}/freeze**
Freezes a specific open channel.| |[Delete a channel](#3_delete_a_channel)|`DELETE` **/open_channels/{channel_url}**
Deletes a specific open channel.|

|Action|HTTP request| |---|---| |[List banned users](#3_list_banned_users)|`GET` **/open_channels/{channel_url}/ban**
Retrieves a list of the banned users from a specific open channel.| |[View a ban](#3_view_a_ban)|`GET` **/open_channels/{channel_url}/ban/{banned_user_id}**
Retrieves details of a ban imposed on the user.| |[Ban a user](#3_ban_a_user)|`POST` **/open_channels/{channel_url}/ban**
Bans a user from a specific open channel.| |[Update a ban](#3_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](#3_unban_a_user)|`DELETE` **/open_channels/{channel_url}/ban/{banned_user_id}**
Unbans the user.| |[List muted users](#3_list_muted_users)|`GET` **/open_channels/{channel_url}/mute**
Retrieves a list of the muted users in a specific open channel.| |[View a mute](#3_view_a_mute)|`GET` **/open_channels/{channel_url}/mute/{muted_user_id}**
Retrieves details of a mute imposed on the user.| |[Mute a user](#3_mute_a_user)|`POST` **/open_channels/{channel_url}/mute
**Mutes a user in a specific open channel.| |[Unmute a user](#3_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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels ``` #### Parameters The following table lists the parameters that this action supports.

|Optional|Type|Description| |---|---|---| |token|string|Specifies a [token](/platform/misc#3_tokens) 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](/platform/quick_start#3_url_encoding).| |url_contains|string|Searches for open channels containing the specified value in their channel URL. It is recommended that the value is [urlencoded](/platform/quick_start#3_url_encoding).| |*~~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](/platform/quick_start#3_url_encoding).*|

```bash ?token=&limit=5&custom_types=live&name_contains=streaming ```

#### Response If **successful**, this action returns a list of [open channel](#4_resource_representation) resources that match the query parameters in the response body.

```json { "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 name|Type|Description| |---|---|---| |channels[]|list|A list of [open channels](#4_resource_representation) 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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url} ``` #### Parameters The following table lists the parameters that this action supports.

|Required|Type|Description| |---|---|---| |channel_url|string|Specifies the URL of the channel to retrieve.|

#### Response If **successful**, this action returns an [open channel](#4_resource_representation) resource in the response body. --- ### Create a channel Creates an open channel. #### HTTP request ```bash POST https://{region_identifier}.sendbird.com/v3/open_channels ``` #### Request body The following table lists the properties of an HTTP request that this action supports.

|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. (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](/platform/quick_start#4_multipart_requests) section.

```json { "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](#4_resource_representation) resource in the response body like the following.

```json { "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 ```bash PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url} ``` #### Parameters The following table lists the parameters that this action supports.

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

|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 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](/platform/quick_start#4_multipart_requests) section. #### Response If **successful**, this action returns an [open channel](#4_resource_representation) 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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/participants ``` #### Parameters The following table lists the parameters that this action supports.

|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 [token](/platform/misc#3_tokens) 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**)|

```bash ?token=&limit=5 ```

#### Response If **successful**, this action returns a list of [user](/platform/user#4_resource_representation) resources that are participating in the open channel in the response body.

```json { "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](/platform/user#4_resource_representation) 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 ```bash PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/freeze ``` #### Parameters The following table lists the parameters that this action supports.

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

|Required|Type|Description| |---|---|---| |freeze|boolean|Determines whether to freeze the channel. (Default: **false**)|

#### Response If **successful**, this action returns an [open channel](#4_resource_representation) resource in the response body. --- ### Delete a channel Deletes an open channel. #### HTTP request ```bash DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url} ``` #### Parameters The following table lists the parameters that this action supports.

|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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban ``` #### Parameters The following table lists the parameters that this action supports.

|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 [token](/platform/misc#3_tokens) 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**)|

```bash ?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=5 ```

#### Response If **successful**, this action returns a list of banned [user](#4_resource_representation) resources and information on each ban in the response body.

```json { "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.| |(ban).user|nested object|The [user](/platform/user#4_resource_representation) resource which constains the simplified information on the banned user.| |(ban).start_at|long|The timestamp of when the ban starts, in [Unix milliseconds](/platform/misc#3_timestamps).| |(ban).end_at|long|The timestamp of when the ban is scheduled to end, in [Unix milliseconds](/platform/misc#3_timestamps).| |(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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id} ``` #### Parameters The following table lists the parameters that this action supports.

|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](#4_resource_representation) resource and information on a ban in the response body. --- ### Ban a user Bans a user from an open channel. #### HTTP request ```bash POST https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban ``` #### Parameters The following table lists the parameters that this action supports.

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

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

```json { "user_id": "Matthew", "seconds": 60, "description": "Too much talking" } ```

#### Response If **successful**, this action returns a [user](#4_resource_representation) resource and information on a ban in the response body.

```json { "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](/platform/user#4_resource_representation) resource which constains the simplified information on the banned user.| |start_at|long|The timestamp of when the ban starts, in [Unix milliseconds](/platform/misc#3_timestamps).| |end_at|long|The timestamp of when the ban is scheduled to end, in [Unix milliseconds](/platform/misc#3_timestamps).| |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 ```bash PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id} ``` #### Parameters The following table lists the parameters that this action supports.

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

|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](#4_resource_representation) resource and information on a ban in the response body. --- ### Unban a user Unbans a user from an open channel. #### HTTP request ```bash DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id} ``` #### Parameters The following table lists the parameters that this action supports.

|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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute ``` #### Parameters The following table lists the parameters that this action supports.

|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 [token](/platform/misc#3_tokens) 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**)|

```bash ?token=&limit=5 ```

#### Response If **successful**, this action returns a list of muted [user](#4_resource_representation) resources and information on a muting in the response body.

```json { "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](/platform/user#4_resource_representation)| |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 ```bash GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id} ``` #### Parameters The following table lists the parameters that this action supports.

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

```json { "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](/platform/misc#3_timestamps), 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](/platform/misc#3_timestamps) format.| |end_at|long|The time in seconds when the user gets unmuted in the channel. The value is in [Unix milliseconds](/platform/misc#3_timestamps) 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. #### HTTP request ```bash POST https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute ``` #### Request body The following table lists the properties of an HTTP request that this action supports.

|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](#4_resource_representation) resource in the response body. --- ### Unmute a user Unmutes a user from an open channel. #### HTTP request ```bash DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id} ``` #### Parameters The following table lists the parameters that this action supports.

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