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.
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. 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. |
/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.
{user_id}
and {channel_url}
.Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
| |
|
Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
|
Retrieves a list of open channels. You can query the list using various parameters.
GET https://api-{application_id}.sendbird.com/v3/open_channels
The following table lists the parameters that this action supports.
Optional | Type | Description |
---|---|---|
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 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. |
| 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. |
?token=&limit=5&custom_types=live&name_contains=streaming
If successful, this action returns a list of open channel resources that match the query parameters in the response body.
{
"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 that match the specifed optional parameters. |
next | string | The value for the token parameter to retrieve the next page in the result set. |
Retrieves information on a specific open channel.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}
The following table lists the parameters that this action supports.
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the channel to retrieve. |
If successful, this action returns an open channel resource in the response body.
Creates an open channel.
POST https://api-{application_id}.sendbird.com/v3/open_channels
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 one or more user IDs to register as operators to 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. |
| 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.
{
"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"
}
If successful, this action returns an open channel resource in the response body like the following.
{
"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
}
Updates information on an open channel.
PUT https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}
The following table lists the parameters that this action supports.
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the channel to update. |
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 one or more user IDs to register as operators to the channel. Operators can delete any messages in the channel, and can also view all messages without any filtering or throttling. |
| 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.
If successful, this action returns an open channel resource in the response body.
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.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/participants
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 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) |
?token=&limit=5
If successful, this action returns a list of user resources that are participating in the open channel in the response body.
{
"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. |
Freezes or unfreezes an open channel.
Note: Only users designated as channel operators are allowed to talk when a channel is frozen.
PUT https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/freeze
The following table lists the parameters that this action supports.
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the channel to freeze. |
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) |
If successful, this action returns an open channel resource in the response body.
Deletes an open channel.
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}
The following table lists the parameters that this action supports.
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the channel to delete. |
If successful, this action returns an empty response body.
Retrieves a list of banned users from a specific open channel.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban
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 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) |
?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=5
If successful, this action returns a list of banned user resources and information on each ban in the response body.
{
"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. |
Retrieves details of a ban imposed on a user.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
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. |
If successful, this action returns a user resource and information on a ban in the response body.
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.
POST https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban
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. |
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 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. |
{
"user_id": "Matthew",
"seconds": 60,
"description": "Too much talking"
}
If successful, this action returns a user resource and information on a ban in the response body.
{
"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. |
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.
PUT https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
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. |
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. |
If successful, this action returns a user resource and information on a ban in the response body.
Unbans a user from an open channel.
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
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. |
If successful, this action returns an empty response body.
Retrieves a list of muted users in the channel.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute
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 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) |
?token=&limit=5
If successful, this action returns a list of muted user resources and information on a muting in the response body.
{
"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. |
Checks if a user is muted in an open channel.
GET https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}
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. |
If successful, this action returns information on a user's muting in the response body.
{
"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. |
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.
POST https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute
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. |
If successful, this action returns an open channel resource in the response body.
Unmutes a user from an open channel.
DELETE https://api-{application_id}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}
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. |
If successful, this action returns an empty response body.