群组白名单管理
大约 9 分钟
REST API
群组白名单管理
即时通讯 IM 提供多个接口实现群组白名单管理，包括查看白名单中的用户以及将用户添加至和移出白名单等。
前提条件
要调用即时通讯 RESTful API，请确保满足以下要求：
- 已在声网控制台开通配置即时通讯 IM 服务。
- 已从服务端获取 app token，详见 使用 Token 鉴权。
- 了解即时通讯 IM API 的调用频率限制，详见 接口频率限制。
公共参数
请求参数
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
host | String | 是 | 即时通讯 IM 分配的用于访问 RESTful API 的域名。 |
app_id | String | 是 | 声网为每个项目自动分配的 App ID，作为项目唯一标识。 |
group_id | String | 是 | 群组 ID。 |
username | String | 是 | 用户 ID。 |
响应参数
| 参数 | 类型 | 描述 |
|---|---|---|
action | String | 请求方法。 |
uri | String | 请求 URL。 |
path | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。 |
entities | JSON | 响应实体。 |
data | JSON | 实际获取的数据详情。 |
created | Long | 群组创建时间，Unix 时间戳，单位为毫秒。 |
timestamp | Long | Unix 时间戳，单位为毫秒。 |
duration | Int | 从发送请求到响应的时长，单位为毫秒。 |
properties | String | 响应属性。 |
认证方式
即时通讯 IM RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：
Authorization: Bearer YourAppToken
为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 IM RESTful API 推荐使用 app token 的 鉴权方式，详见 使用 Token 鉴权。
查询群组白名单
查询群组白名单中的用户列表。
HTTP 请求
GET https://{host}/app-id/{app_id}/chatgroups/{group_id}/white/users
路径参数
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
data | Array | 群组白名单中的用户 ID 列表。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatgroups/{groupid}/white/users'
响应示例
{
"action": "get",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users",
"entities": [],
"data": [
"wzy_test",
"wzy_vivo",
"wzy_huawei",
"wzy_xiaomi",
"wzXXXXzu"
],
"timestamp": 1594724947117,
"duration": 3,
"count": 5
}
错误码
如果返回的 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}/app-id/{app_id}/chatgroups/{group_id}/white/users/{username}
路径参数
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
username | String | 是 | 要加入群组白名单的用户 ID。 |
参数及描述详见 公共参数。
请求 header
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json。 |
Authorization | String | 是 | App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：
| 字段 | 描述 |
|---|---|
data.result | 添加结果： - true：添加成功；- false：添加失败。 |
data.action | 执行操作。在该响应中，该字段的值为 add_user_whitelist，表示将成员加入群白名单。 |
data.user | 添加的用户 ID。 |
data.groupid | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatgroups/{groupid}/white/users/{username}'
响应示例
{
"action": "post",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users/wzy_xiaomi",
"entities": [],
"data": {
"result": true,
"action": "add_user_whitelist",
"user": "wzy_xiaomi",
"groupid": "12XXXX53"
},
"timestamp": 1594724293063,
"duration": 4
}
错误码
如果返回的 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 请求
POST https://{host}/app-id/{app_id}/chatgroups/{group_id}/white/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_user_whitelist，表示将成员加入群白名单。 |
- user | String | 添加的用户 ID。 |
- groupid | String | 群组 ID。 |
- reason | String | 添加失败的原因。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{"usernames" : ["user1"]}' 'https://XXXX/app-id/XXXX/chatgroups/{groupid}/white/users'
响应示例
{
"action": "post",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users",
"entities": [],
"data": [
{
"result": true,
"action": "add_user_whitelist",
"user": "wzy_test",
"groupid": "12XXXX53"
},
{
"result": true,
"action": "add_user_whitelist",
"user": "wzXXXXzu",
"groupid": "12XXXX53"
}
],
"timestamp": 1594724634191,
"duration": 2
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 400 | invalid_parameter | usernames size is more than max limit : 60 | 批量添加白名单的群成员超过了上限 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。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。
从群组白名单移除用户
将指定用户从群组白名单中移除。你每次最多可移除 60 个用户。
HTTP 请求
DELETE https://{host}/app-id/{app_id}/chatgroups/{group_id}/white/users/{username}
路径参数
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
username | String | 是 | 要从群组白名单中移除的用户 ID，最多可传 60 个，用户 ID 之间以英文逗号（","）分隔。 |
其他参数及描述详见 公共参数。
请求 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_user_whitelist，表示将成员移出群组白名单。 |
- user | String | 移除群组白名单的用户 ID。 |
- groupid | String | 群组 ID。 |
其他字段及描述详见 公共参数。
如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatgroups/{groupid}/white/users/{username}'
响应示例
{
"action": "delete",
"uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users/wzy_huawei,wzXXXXzu",
"entities": [],
"data": [
{
"result": true,
"action": "remove_user_whitelist",
"user": "wzy_huawei",
"groupid": "12XXXX53"
},
{
"result": true,
"action": "remove_user_whitelist",
"user": "wzXXXXzu",
"groupid": "12XXXX53"
}
],
"timestamp": 1594725137704,
"duration": 1
}
错误码
如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
|---|---|---|---|---|
| 400 | invalid_parameter | removeWhitelist size is more than max limit : 60 | 批量移除白名单的群成员数量超过了上限 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。 |
关于其他错误，你可以参考 响应状态码 了解可能的原因。