管理社区及其成员

社区（Server）是一群有着共同兴趣爱好的人的专属天地，也可以是同学朋友的社交圈子。社区是环信圈子三层基础架构的最上层，各种消息事件均发生在社区内。社区分为公开社区和私密社区。用户可查询公开社区列表，但无法查询私密社区列表。

超级社区中的频道基于即时通讯 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 ${YourAppToken}

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

查询环信超级社区用户是否存在。

GET https://{host}/{orgName}/{appName}/circle/user/{user_id}

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/user/{user_id}'

{
    "code": 200,
    "result" : true
}

查询 App 下的社区列表，包括公开和私密社区。

GET https://{host}/{org_name}/{app_name}/circle/server/list/by-app?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/server/list/by-app?limit=1&cursor=XXX'

{
    "code": 200,
    "count": 1,
    "servers": [
        {
          "name": "server",
          "owner": "user1",
          "type": 0,
          "description": "community",
          "custom": "custom",
          "created": 1658126097514,
          "server_id": "19SW5Q85jHxxxxx6T5kexvn",
          "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
          "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
          "default_channel_id": "187xxxx09"
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

社区分为公开社区和私密社区。每个用户最多可以创建 100 个社区。

创建社区时，需设置社区名称、社区类型、社区头像的 URL、社区描述、社区背景 URL 和社区扩展信息。

POST https://{host}/{org_name}/{app_name}/circle/server

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

如果返回的 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/server' -d '{
 "owner" : "user1",
 "name" : "server",
 "type" : 0,
 "icon_url" : "http://circle.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
 "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
 "description" : "community",
 "default_channel_category_name" : "category0", 
 "default_channel_name" : "channel0",
 "custom" : "custom"
}'

{
    "code": 200,
    "server_id": "19VM9oPBasxxxxxx0tvWViEsdM"
}

修改指定社区的信息。你可以修改社区名称、社区头像的 URL、社区描述和社区的扩展信息。

PUT https://{host}/{org_name}/{app_name}/circle/server/{server_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/server/XXX' -d '{
 "name" : "easemob",
 "icon_url" : "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
 "description" : "community",
 "custom" : ""custom"
}'

{
    "code": 200,
    "server": {
        "name": "server",
        "owner": "user1",
        "type": 0,
        "description": "community",
        "custom": "custom",
        "tags": [
            {
                "server_tag_id": "1",
                "tag_name": "社交"
            }
        ],
        "tag_count": 1,
        "created": 1658126097514,
        "server_id": "19SW5Q85jHxxxxx6T5kexvn",
        "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
        "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
        "default_channel_id": "187xxxx09"
    }
}

每个社区最多可以添加 10 个标签。

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/tag/add

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

如果返回的 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/server/XXX/tag/add' -d '{
 "tags": ["社交"]
}'

{
    "code": 200,
    "tags": [
        {
            "server_tag_id": "1",
            "tag_name": "社交"
        }
    ]
}

获取指定社区的标签。

GET https://{host}/{orgName}/{appName}/circle/server/{server_id}/tag

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

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourToken>' 'http://XXX/XXX/XXX/circle/server/XXX/tag'

{
    "code": 200,
    "count": 1,
    "tags": [
        {
            "server_tag_id": "78",
            "tag_name": "uur2"
        }
    ]
}

根据标签的 ID 移除标签，不能使用标签名进行移除。移除标签之前，你可以通过获取社区详情获取标签 ID。

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/tag/remove

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

如果返回的 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/server/XXX/tag/remove' -d '{
 "tagIds" : ["1", "2"]
}'

{
    "code": 200
}

你可以根据社区名称或者标签名称搜索公共社区。

GET https://{host}/{org_name}/{app_name}/circle/server/search/{name}?type=0&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/server/search/XXX'

{
    "code": 200,
    "count": 1,
    "servers": [
        {
          "name": "server",
          "owner": "user1",
          "type": 0,
          "description": "community",
          "custom": "custom",
          "created": 1658126097514,
          "server_id": "19SW5Q85jHxxxxx6T5kexvn",
          "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
          "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
          "default_channel_id": "187xxxx09"
        }
    ]
}

获取指定社区的详情。

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/by-id

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

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX/by-id'

{
    "code": 200,
    "server": {
        "name": "server",
        "owner": "user1",
        "type": 0,
        "description": "community",
        "custom": "custom",
        "tags": [
            {
                "server_tag_id": "1",
                "tag_name": "社交"
            }
        ],
        "tag_count": 1,
        "created": 1658126097514,
        "server_id": "19SW5Q85jHxxxxx6T5kexvn",
        "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
        "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
        "default_channel_id": "187xxxx09"
    }
}

目前，该方法返回最新创建的 5 个社区的详情。若社区数量少于 5 个，则返回实际的社区数量。

GET https://{host}/{org_name}/{app_name}/circle/server/recommend/list

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

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

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

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

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

{
    "code": 200,
    "count": 1,
    "servers": [
        {
          "name": "server",
        	"owner": "user1",
          "type": 0,
          "description": "community",
          "custom": "custom",
          "tags": [
              {
                  "server_tag_id": "1",
                  "tag_name": "社交"
              }
          ],
          "tag_count": 1,
          "created": 1658126097514,
          "server_id": "19SW5Q85jHxxxxx6T5kexvn",
          "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
          "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
          "default_channel_id": "187xxxx09"
        }
    ]
}

分页获取当前用户加入的社区的详情。

GET https://{host}/{org_name}/{app_name}/circle/server/list?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/server/list?userId=XXX&limit=1&cursor=XXX'

{
    "code": 200,
    "count": 1,
    "servers": [
        {
          "name": "server",
          "owner": "user1",
          "type": 0,
          "description": "community",
          "custom": "custom",
          "tags": [
              {
                  "server_tag_id": "1",
                  "tag_name": "社交"
              }
          ],
          "tag_count": 1,
          "created": 1658126097514,
          "server_id": "19SW5Q85jHxxxxx6T5kexvn",
          "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
          "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
          "default_channel_id": "187xxxx09"
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

删除指定的社区。删除社区后，该社区中的频道分组和频道也将被删除。

DELETE https://{host}/{org_name}/{app_name}/circle/server/{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/server/XXX'

{
    "code": 200
}

分页获取社区成员列表。

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/users?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/server/XXX/users?limit=1&cursor=XXX'

{
    "code": 200,
    "count": 1,
    "users": [
        {
            "user_id" : "user1",
            "role" : 0
        }
    ],
    "cursor": "ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aXXXXXXXXXXXXXX"
}

查询社区内的成员总数。

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/users/count

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

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX/users/count'

{
    "code": 200,
    "users_count" : 10
}

将单个用户加入社区，每个用户最多可加入 100 个社区。

用户加入社区时会自动加入社区的默认频道。默认情况下，社区的默认频道最多可包含 2000 个用户。若达到该阈值，则用户加入社区失败。

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/join?userId={user_id} 

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

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

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

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

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

{
    "code": 200,
    "server": {
        "name": "server",
        "owner": "user1",
        "type": 0,
        "description": "community",
        "custom": "custom",
        "tags": [
            {
                "server_tag_id": "1",
                "tag_name": "社交"
            }
        ],
        "tag_count": 1,
        "created": 1658126097514,
        "server_id": "19SW5Q85jHxxxxx6T5kexvn",
        "icon_url": "http://discord.oss/19b1d7b0-7079-11e9-9bd8-25c5e81b42a1",
        "background_url" : "http://circle.oss/89c2e7p8-8794-3u4k-80n5-56m9e8c28b29",
        "default_channel_id": "187xxxx09"
    }
}

查询用户是否在社区内。

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/user/{user_id} 

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

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

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

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

{
    "code": 200,
    "result": true
}

查询指定成员在社区内的角色。

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/user/role?userId={user_id} 

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

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX/user/role?userId=XXX'

{
    "code": 200,
    "role" : 1
}

修改社区中指定成员的角色。

PUT https://{host}/{org_name}/{app_name}/circle/server/{server_id}/user/role?userId={user_id}&role={role} 

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X PUT -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX/user/role?userId=XXX&role=XXX'

{
    "code": 200
}

将指定成员移出社区。一旦成员被移出社区，该成员会自动被移出该社区下的所有频道。

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/user/remove?userId={user_id}

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

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

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

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX/user/remove?userId=XXX'

{
    "code": 200
}