群组黑名单管理
大约 12 分钟
REST API
群组黑名单管理
环信即时通讯 IM 提供多个接口实现群组黑名单管理，包括查询群组黑名单、将成员添加和移除聊天室黑名单。
前提条件
要调用环信即时通讯 RESTful API，请确保满足以下要求：
- 已在环信即时通讯 IM 管理后台 开通配置环信即时通讯 IM 服务。
- 了解环信 IM RESTful API 的调用频率限制，详见 接口频率限制。
- 群成员的相关限制，详见 使用限制。
公共参数
请求参数
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
host | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息。 |
org_name | String | 是 | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 获取环信即时通讯 IM 的信息。 |
app_name | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息。 |
group_id | String | 是 | 群组 ID。 |
username | String | 是 | 用户 ID。 |
响应参数
| 参数 | 类型 | 描述 |
|---|---|---|
action | String | 请求方法。 |
organization | String | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 org_name 相同。 |
application | String | 应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。 |
applicationName | String | 你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 app_name 相同。 |
uri | String | 请求 URL。 |
path | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。 |
entities | JSON | 响应实体。 |
data | JSON | 实际获取的数据详情。 |
created | Long | 群组创建时间，Unix 时间戳，单位为毫秒。 |
timestamp | Long | Unix 时间戳，单位为毫秒。 |
duration | Int | 从发送请求到响应的时长，单位为毫秒。 |
properties | String | 响应属性。 |
认证方式
环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：
Authorization: Bearer YourAppToken
为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 使用 App Token 鉴权。
查询群组黑名单
查询一个群组黑名单中的用户列表。黑名单中的用户无法查看该群组的信息，也无法收到该群组的消息。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
路径参数
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
count | Int | 群组黑名单中的用户数量。 |
data | Array | 群组黑名单上的用户 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users'
响应示例
{
"action": "get",
"application": "8bXXXX02",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/67178793598977/blocks/users",
"entities": [],
"data": ["user2", "user3"],
"timestamp": 1543466293681,
"duration": 0,
"organization": "XXXX",
"applicationName": "testapp",
"count": 2
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
| 404 | resource_not_found | grpID XX does not exist! | 群组不存在。 | 使用合法的群 ID。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。
添加单个用户至群组黑名单
将单个用户添加至群组黑名单。群主无法被加入群组的黑名单。
用户进入群组黑名单后会收到加入黑名单的回调。之后，该用户无法查看该群组的信息，也收不到该群组的消息。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
路径参数
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json。 |
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
data.result | Bool | 添加结果： - true：添加成功；- false：添加失败。 |
data.action | String | 执行操作。在该响应中，该字段的值为 add_blocks，表示将成员添加至群组黑名单。 |
data.user | String | 添加的用户 ID。 |
data.groupid | String | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1'
响应示例
{
"action": "post",
"application": "8bXXXX02",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1",
"entities": [],
"data": {
"result": true,
"action": "add_blocks",
"user": "user1",
"groupid": "66XXXX85"
},
"timestamp": 1542539577124,
"duration": 27,
"organization": "XXXX",
"applicationName": "testapp"
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
| 403 | forbidden_op | users [XX] are not members of this group! | 要添加黑名单的用户 ID 不在群组中。 | 使用群组成员的用户 ID。 |
| 404 | resource_not_found | grpID XX does not exist! | 群组不存在。 | 使用合法的群 ID。 |
| 403 | forbidden_op | forbidden operation on group owner! | 无法将群主加入群组黑名单。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。
批量添加用户至群组黑名单
将多个用户添加至群组黑名单，一次最多可以添加 60 个用户。群主无法被加入群组的黑名单。
用户进入群组黑名单后会收到加入黑名单的回调。黑名单上的用户无法查看该群组的信息，也收不到该群组的消息。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
路径参数
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json。 |
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
请求 body
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
usernames | Array | 是 | 要添加至群组黑名单的用户 ID 数组，每次最多可传 60 个用户 ID。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
data | JSON Array | 响应数据。 |
- result | Bool | 添加结果： - true：添加成功；- false：添加失败。 |
- action | String | 执行的操作。在该响应中，该字段的值为 add_blocks，表示将群成员加入群组黑名单。 |
- reason | String | 添加失败的原因。 |
- user | String | 添加的用户 ID。 |
- groupid | String | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
"usernames": [
"user3","user4"
]
}' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users'
响应示例
{
"action": "post",
"application": "8bXXXX02",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users",
"entities": [],
"data": [
{
"result": false,
"action": "add_blocks",
"reason": "user: user3 doesn't exist in group: 66XXXX85",
"user": "user3",
"groupid": "66XXXX85"
},
{
"result": true,
"action": "add_blocks",
"user": "user4",
"groupid": "66XXXX85"
}
],
"timestamp": 1542540095540,
"duration": 16,
"organization": "XXXX",
"applicationName": "testapp"
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 400 | invalid_parameter | userNames is more than max limit : 60 | 批量添加的用户数超过了上限 60。 | 调整要移除的数量在限制以下。 |
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
| 403 | forbidden_op | users [XX] are not members of this group! | 要添加黑名单的用户 ID 不在群组中。 | 使用群组成员的用户 ID。 |
| 404 | resource_not_found | grpID XX does not exist! | 群组不存在。 | 使用合法的群 ID。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。
从群组黑名单移除单个用户
将指定用户移出群组黑名单。对于群组黑名单中的用户，如果需要将其再次加入群组，需要先将其从群组黑名单中移除。
HTTP 请求
DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
路径参数
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
result | Bool | 移除结果： - true：移除成功；- false：移除失败。 |
action | String | 执行的操作。在该响应中，该字段的值为 remove_blocks，表示将群成员移出群组黑名单。 |
user | String | 添加的用户 ID。 |
groupid | String | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1'
响应示例
{
"action": "delete",
"application": "8bXXXX02",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1",
"entities": [],
"data": {
"result": true,
"action": "remove_blocks",
"user": "user1",
"groupid": "66XXXX85"
},
"timestamp": 1542540470679,
"duration": 45,
"organization": "XXXX",
"applicationName": "testapp"
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
| 403 | forbidden_op | users [XX] are not members of this group! | 要移除黑名单的用户 ID 不在群组中。 | 传入群组黑名单中的群成员的用户 ID。 |
| 404 | resource_not_found | grpID XX does not exist! | 群组不存在。 | 使用合法的群 ID。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。
从群组黑名单批量移除用户
将多名指定用户从群组黑名单中移除。你一次最多可移除 60 个用户。
对于群组黑名单中的用户，如果要将其再次加入群组，需先将其从群组黑名单中移除。
HTTP 请求
DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{usernames}
路径参数
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
usernames | String | 是 | 要移除群组黑名单的用户 ID，一次最多可传 60 个，用户 ID 之间以英文逗号（","）分隔，逗号在 URL 中转义为 "%2C"。 |
其他参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
data | JSON Array | 响应数据。 |
- result | Bool | 移除结果： - true：移除成功；- false：移除失败。 |
- action | String | 执行的操作。在该响应中，该字段的值为 remove_blocks，表示将用户从群组黑名单批量移除。 |
- user | String | 被移除的用户 ID。 |
- groupid | String | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1%2Cuser2'
响应示例
{
"action": "delete",
"application": "8bXXXX02",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1%2Cuser2",
"entities": [],
"data": [
{
"result": true,
"action": "remove_blocks",
"user": "user1",
"groupid": "66XXXX85"
},
{
"result": true,
"action": "remove_blocks",
"user": "user2",
"groupid": "66XXXX85"
}
],
"timestamp": 1542541014655,
"duration": 29,
"organization": "XXXX",
"applicationName": "testapp"
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 400 | invalid_parameter | removeBlacklist: list size more than max limit : 60 | 批量删除超过上限 60。 | 调整要移除的数量在限制以下。 |
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
| 403 | forbidden_op | users [XX] are not members of this group! | 要移除黑名单的用户 ID 不在群组中。 | 传入群组黑名单中的群成员的用户 ID。 |
| 404 | resource_not_found | grpID XX does not exist! | 群组不存在。 | 使用合法的群 ID。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。