管理社区及其成员

大约 29 分钟

管理社区及其成员

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

超级社区中的频道基于即时通讯 IM 的群组或聊天室(频道 ID 为群组 ID 或聊天室 ID)创建,解散群组或聊天室时需注意以下几点:

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

前提条件

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

公共参数

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见获取环信即时通讯 IM 的信息open in new window
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见获取环信即时通讯 IM 的信息open in new window
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见获取环信即时通讯 IM 的信息open in new window
server_idString社区 ID。
channel_idString频道 ID。
user_idString用户 ID。
roleInt用户的角色:
- 0:社区所有者;
- 1:社区管理员;
- 2:社区的普通成员。

提示

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

响应参数

参数类型描述
nameString社区名称。
ownerString社区的所有者。
typeInt社区的类型:
- 0:公开社区;
- 1:私密社区。
descriptionString社区描述。
customString社区的扩展信息。
icon_urlString社区头像的 URL。
background_urlString社区背景的 URL。
server_tag_idString社区标签 ID。
tag_nameString社区标签名称。
tag_countInt社区标签数量。
server_idString社区 ID。
default_channel_idString社区的默认频道的 ID。
user_idString环信用户 ID。
roleInt社区成员的角色:
- 0:社区所有者;
- 1:社区管理员;
- 2:社区的普通成员。
createdLong社区的创建时间,Unix 时间戳,单位为毫秒。

认证方式

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

Authorization:Bearer ${YourAppToken}

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

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

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

HTTP 请求

GET https://{host}/{org_name_}/{app_name}/circle/user/{user_id}
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
resultBoolean查询结果:
- true:用户存在;
- false:用户不存在。

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

示例

请求示例
<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 下的社区列表

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/list/by-app?limit={limit}&cursor={cursor}
路径参数

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
limitInt每页获取的社区数量。取值范围为 [1,20],默认值为 20。该参数仅在分页查询时设置。
cursorString游标,指定数据查询的开始位置。该参数仅在分页查询时设置。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
countInt获取到的社区数量。
serversList获取到的社区详情。
cursorString游标,下次数据查询的起始位置。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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 和社区扩展信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/circle/server
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。
请求 body
参数类型是否必需描述
ownerString社区创建者(即社区所有者)的用户 ID,长度不能超过 64 字节。
nameString社区名称,长度不能超过 50 个字符。
typeInt社区的类型:
- (默认)0:公开社区;
- 1:私密社区。
icon_urlString社区头像的 URL,长度不能超过 500 个字符。
background_urlString社区背景的 URL,长度不能超过 500 个字符。
descriptionString社区描述,长度不能超过 500 个字符。
default_channel_category_nameString默认频道分组的名称。如果不指定,该频道分组的名称默认为 文字频道
default_channel_nameString默认频道的名称。如果不指定,该频道的名称默认为 通用
customString社区的扩展信息,例如,你可以给社区添加业务相关的标记,长度不能超过 500 个字符。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
server_idString社区 ID。

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

示例

请求示例
<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、社区描述和社区的扩展信息。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/circle/server/{server_id} 
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。
请求 body
参数类型是否必需备注
nameString社区名称,长度不能超过 50 个字符。
typeInt社区类型:
- 0:公开社区;
- 1:私密社区。
icon_urlString社区头像的 URL,长度不能超过 500 个字符。
background_urlString社区背景的 URL,长度不能超过 500 个字符。
descriptionString社区描述,长度不能超过 500 个字符。
customString社区的扩展信息,例如,可以给社区添加业务相关的标记,长度不能超过 500 个字符。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
serverList社区数据。
tagsList社区标签数据。

其他字段及描述详见 公共参数open in new window

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

示例

请求示例
<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 个标签。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/tag/add
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。
请求 body
参数类型是否必需描述
tagsList为社区添加标签的数组,最多可以添加 10 个标签,每个标签的长度不能超过 20 个字符。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
tagsList社区标签数据。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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": "社交"
        }
    ]
}

获取社区标签

获取指定社区的标签。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/tag
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
countInt社区标签数量。
tagsList社区标签数据。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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 移除标签,不能使用标签名进行移除。移除标签之前,你可以通过获取社区详情open in new window获取标签 ID。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/circle/server/{server_id}/tag/remove
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。
请求 body
参数类型是否必需描述
tagIdsList要移除的社区标签 ID 的数组,一次移除的标签不能超过 10 个。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。

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

示例

请求示例
<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
}

搜索公共社区

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/search/{name}?type=0&limit={limit}&cursor={cursor} 
路径参数
参数类型是否必需描述
nameString社区名称或社区标签名称。社区名称不能超过 50 个字符,标签名称不能超过 20 个字符。
- 根据社区名称搜索,支持基于通过社区全名搜索和模糊搜索分页获取数据。若使用模糊搜索,你需要传入社区名称中最左侧的单个字或词汇,或包含该字或词汇的关键字,例如社区名称为 足球社区01,传入 足球 都可搜索出该社区,而使用 社区01 则搜索不到该社区。
- 若根据标签名称搜索,需传入完整的标签名称,不支持模糊搜索。

其他参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
typeInt搜索类型:
- (默认)0:根据社区名称分页获取社区列表。这种情况下,需将路径参数中的 name 设置为社区名称并设置 limitcursor
- 1:根据标签名称获取社区列表,直接获取带有该标签的所有社区。这种情况下,需将路径参数中的 name 设置为社区标签名称,而无需设置 limitcursor
limitInt每页获取的社区数量。取值范围为 [1,20],默认值为 20。该参数仅在分页获取时为必需。
cursorString游标,指定数据查询的起始位置。该参数仅在分页获取时为必需。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
serversList获取的社区详情。
countInt获取的社区数量。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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"
        }
    ]
}

获取指定社区的详情

获取指定社区的详情。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/by-id
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
serverList社区的详情。
tagsList社区标签数据。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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 个,则返回实际的社区数量。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/recommend/list
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
serversList推荐的社区的详情。
tagsList推荐的社区的标签数据。
countInt推荐的社区的数量。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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"
        }
    ]
}

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

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/list?userId={user_id}&limit={limit}&cursor={cursor} 
路径参数

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
user_idString用户 ID。
limitInt每页获取的社区数量。取值范围为 [1,20],默认值为 20
cursorString游标,指定数据查询的起始位置。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
countInt获取到的社区数量。
serversList获取到的社区详情。
tagsList用户加入的社区的标签数据。
cursorString游标,下次数据查询的起始位置。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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"
}

删除社区

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/circle/server/{server_id}
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。

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

示例

请求示例
<YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXX/XXX/XXX/circle/server/XXX'
响应示例
{
    "code": 200
}

管理社区成员

获取社区成员列表

分页获取社区成员列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/users?limit={limit}&cursor={cursor} 
路径参数

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
limitInt每页获取的社区成员数量。取值范围为 [1,20],默认值为 20。该参数仅在分页获取时为必需。
cursorString游标,指定数据查询的起始位置。该参数仅在分页获取时为必需。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
countInt获取到的社区成员数量。
usersList获取到的社区成员详情。
cursorString游标,下次数据查询的起始位置。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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"
}

获取社区内的成员总数

查询社区内的成员总数。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/users/count
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
users_countLong社区内成员总数。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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 个用户。若达到该阈值,则用户加入社区失败。

HTTP 请求

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

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
user_idString用户 ID。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
serverList用户加入的社区的详情。
tagsList用户加入的社区的标签数据。

其他字段及描述详见公共参数open in new window

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

示例

请求示例
<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"
    }
}

查询用户是否在社区内

查询用户是否在社区内。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/circle/server/{server_id}/user/{user_id} 
路径参数

参数及描述详见公共参数open in new window

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。
resultBoolean查询结果:
- true:用户在社区中;
- false:用户不在社区中。

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

示例

请求示例
<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
}

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

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

HTTP 请求

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

参数及描述详见公共参数open in new window

查询参数
参数类型描述是否必需
user_idString用户 ID。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。

其他字段及描述详见 公共参数open in new window

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

示例

请求示例
<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
}

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

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

HTTP 请求

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

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
user_idString用户 ID。
roleInt要修改的成员角色,只能传以下值:
- 1:表示社区管理员;
- 2:表示普通成员。
若传 0(表示社区所有者)或其他无效值时会报错。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourApp Token},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。

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

示例

请求示例
<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
}

将成员移出社区

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

HTTP 请求

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

参数及描述详见公共参数open in new window

查询参数
参数类型是否必需描述
user_idString用户 ID。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationString该管理员的鉴权 App Token,格式为 Bearer ${YourAppToken},其中 Bearer 是固定字符,后面加英文空格,再加获取到的 App Token 值。

HTTP 响应

响应 body

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

字段类型描述
codeInt环信超级社区的服务状态码。

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

示例

请求示例
<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
}