管理社区频道分组

环信超级社区（Circle）支持频道分组方便频道管理。例如，可将歌剧频道、民歌频道和流行歌曲频道划分为声乐频道分组。

社区创建时会创建默认的频道分组，包含默认频道。

超级社区中的频道基于即时通讯 IM 的群组或聊天室（频道 ID 为群组 ID 或聊天室 ID）创建，删除群组或聊天室时需注意以下几点：

1. 在环信控制台或者调用 RESTful API 删除群组或聊天室、群组或聊天室加人、踢人等操作时请谨慎操作，需确保操作的群组或者聊天室不是超级社区使用的。
2. 如果将超级社区使用的频道对应的群组或者聊天室删除，会出现数据不一致情况，导致用户加入不了社区、频道、在频道内发不了消息等情况发生。
3. 在清理群组或者聊天室数据时，需先确认要删除的群组 ID 或聊天室 ID 与超级社区的频道 ID 是否一致。你可以调用获取频道详情 API 确认要删除的群组或聊天室是否为超级社区的频道。如果是，请不要进行删除。
4. 如果需要清理超级社区数据，调用删除社区和删除频道等 API。

要调用环信即时通讯 RESTful API，请确保满足以下要求：

• 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
• 了解环信 IM RESTful API 的调用频率限制，详见 接口频率限制。

对于分页获取数据列表，若查询参数中的 limit 和 cursor 均未设置，则服务器返回首页的数据列表。

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization：Bearer ${YourToken}

为提高项目的安全性，环信使用 App Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 需使用 App Token 的鉴权方式，详见 使用环信 App Token 鉴权。

在社区下创建一个频道分组，将多个频道归入一个频道分组方便管理。

每个社区下最多可以创建 50 个频道分组。每个频道只能加入一个频道分组。

POST https://{host}/{org_name}/{app_name}/circle/channel/category

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category' -d '{
 		"server_id" : "19SW5Q85jHxxxxx6T5kexvn",
 		"name" : "channel category name"
}'

{
    "code": 200,
    "channel_category_id": "77a9860xxxxxx2b54881025861c",
}

修改指定社区下的特定频道分组的名称。

PUT https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及描述详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX' -d '{
 		"server_id" : "19SW5Q85jHxxxxx6T5kexvn",
 		"name" : "update channel category name"
}'

{
    "code": 200,
    "channelCategory": {
				"name": "update channel category name",
				"created": 1667471759201,
				"server_id": "19SW5Q85jHxxxxx6T5kexvn",
				"channel_category_id": "77a9860xxxxxx2b54881025861c"
		}
}

删除指定社区下的特定频道分组。删除频道分组后，该频道分组下的所有频道会添加到社区的默认频道分组中。

DELETE https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}?serverId={server_id}

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX?serverId=XXX'

{
    "code": 200
}

将指定频道从当前频道分组转移至其他频道分组。

POST 
http://{host}/{org_name}/{app_name}/circle/channel/category/member/transfer?serverId={server_id}&channelCategoryId={channel_category_id}&channelId={channel_id}

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/member/transfer?serverId=XXX&channelCategoryId=XXX&channelId=XXX'

{
    "code": 200
}

分页获取指定社区下的频道分组列表。

GET https://{host}/{org_name}/{app_name}/circle/channel/category/list?serverId={server_id}&limit={limit}&cursor={cursor} 

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/list?serverId=XXX'

{
    "code": 200,
    "count": 1,
    "channelCategoryList": [
        {
        		"name": "channel category name",
				"created": 1667471759201,
				"server_id": "19SW5Q85jHxxxxx6T5kexvn",
				"channel_category_id": "77a9860xxxxxx2b54881025861c"
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

分页获取指定频道分组下的所有频道的列表（包括公开和私密频道）。

GET https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}/member/list?serverId={server_id}&limit={limit}&cursor={cursor} 

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX/member/list?serverId=xxx?limit={limit}&cursor={cursor}'

{
    "code": 200,
    "count": 1,
    "channels": [
        {
        		"owner": "user1",
        		"name": "chat channel",
        		"type": 0,
        		"mode": 0,
        		"description": "chat channel",
        		"custom": "custom",
        		"created": 1675845650856,
        		"server_id": "19VM9oPBasxxxxxx0tvWViEsdM",
        		"channel_category_id": "77a9860xxxxxx2b54881025861c",
        		"channel_id": "2059xxxxxx1542",
        		"max_users": 200,
        		"default_channel": 0
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

分页获取指定频道分组下的公开频道列表。

GET https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}/public/member/list?serverId={server_id}&limit={limit}&cursor={cursor} 

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX/public/member/list?serverId=XXX'

{
    "code": 200,
    "count": 1,
    "channels": [
        {
        		"owner": "user1",
        		"name": "chat channel",
        		"type": 0,
        		"mode": 0,
        		"description": "chat channel",
        		"custom": "custom",
        		"created": 1675845650856,
        		"server_id": "19VM9oPBasxxxxxx0tvWViEsdM",
        		"channel_category_id": "77a9860xxxxxx2b54881025861c",
        		"channel_id": "2059xxxxxx1542",
        		"max_users": 200,
        		"default_channel": 0
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

分页获取频道分组下的私密频道列表。

GET https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}/private/member/list?serverId={server_id}&limit={limit}&cursor={cursor} 

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX/private/member/list?serverId=XXX'

{
    "code": 200,
    "count": 1,
    "channels": [
        {
        		"owner": "user1",
        		"name": "chat channel",
        		"type": 1,
        		"mode": 0,
        		"description": "chat channel",
        		"custom": "custom",
        		"created": 1675845650856,
        		"server_id": "19VM9oPBasxxxxxx0tvWViEsdM",
        		"channel_category_id": "77a9860xxxxxx2b54881025861c",
        		"channel_id": "2090xxxxxx2369",
        		"max_users": 200,
        		"default_channel": 0
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

分页获取指定频道分组下用户加入的频道 ID 列表。

GET https://{host}/{org_name}/{app_name}/circle/channel/category/{channel_category_id}/user/joined/member/list?serverId={server_id}&userId={user_id}&limit={limit}&cursor={cursor} 

参数及描述详见公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/channel/category/XXX/user/joined/member/list?serverId=XXX&userId=XXX'

{
    "code": 200,
    "count": 1,
    "channelIds": [
        "2090xxxxxx2369"
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}