用户全局禁言
更新时间:2022 年 5 月 19 日
功能概述
随着监管机制日益完善,对 app 的监管不断加强,安全合规逐渐成为 app 的生命线。
为加强 app 管理,环信即时通讯提供全局禁言功能,对 app 提供用户 ID 级别的禁言管理,支持在管理员发现用户违规后进行全局禁言,以维护 app 良好的内容生态环境。禁言到期后,服务器会自动解除禁言,恢复该用户发送消息的权限。
你可以对单个用户 ID 设置单聊、群组或聊天室消息全局禁言。禁言后,该用户将无法在对应的单聊、群组或聊天室发送消息;无论通过调用客户端 API,还是使用服务端 RESTful API 都不行。
该功能可广泛应用于实时互动 app 中,例如发现某用户频繁向多个聊天室发送违规广告,则可以对该用户开启全局聊天室禁言 15 天;发现某用户发表触犯红线的政治言论,则可以全局永久禁言,用户申诉通过后可以解禁。
认证方式
环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。本文 REST API 仅支持使用 app token,详见使用 app Token 鉴权。
设置用户全局禁言
设置单个用户 ID 的单聊、群组、聊天室消息全局禁言。
基本信息
请求方法:POST
接入点: https://{host}/{orgName}/{appName}/mutes
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
orgName | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
appName | String | 必需 | 您在环信管理后台创建的 APP 名称。 |
请求参数说明
字段 | 类型 | 是否必需 | 字段说明 |
---|---|---|---|
username | string | 必需 | 设置禁言配置的用户 ID。 |
chat | integer | 非必需 | 单聊消息禁言时长,单位为秒,最大值为 2147483647。 * > 0 :该用户 ID 具体的单聊消息禁言时长。 * 0 :取消该用户的单聊消息禁言。* -1 :该用户被设置永久单聊消息禁言。* 如果设为其他负值,则取值无效。 |
groupchat | integer | 非必需 | 群组消息禁言时长,单位为秒,规则同上。 |
chatroom | integer | 非必需 | 聊天室消息禁言时长,单位为秒,规则同上。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Authorization | String | 必需 | 鉴权 token,管理员 token(含)以上权限。 |
响应体参数
参数 | 类型 | 描述 |
---|---|---|
result | String | 该方法调用结果。ok 表示设置成功。 |
请求示例
curl -L -X POST 'https://a1.easemob.com/easemob-demo/testappkey/mutes' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json' \
--data-raw '{
"username": "zs1",
"chat": 100,
"groupchat": 100,
"chatroom": 100
}'
响应示例
{
"path": "/mutes",
"uri": "https://a1.easemob.com/easemob-demo/testappkey/mutes",
"timestamp": 1631609754727,
"organization": "easemob-demo",
"application": "357169f0-492a-11e9-9b3a-f1af649cc48d",
"action": "post",
"data": {
"result": "ok"
},
"duration": 74,
"applicationName": "testappkey"
}
查询单个用户 ID 全局禁言
查询单个用户的单聊/群聊/聊天室消息禁言。
基本信息
方法:GET
接入点:https://{host}/{orgName}/{appName}/mutes/username
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
orgName | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
appName | String | 必需 | 您在环信管理后台创建的 APP 名称。 |
username | String | 必需 | 查询禁言信息的用户 ID。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | application/json 内容类型。 |
Authorization | String | 必需 | 鉴权 token,管理员 token (含)以上权限。 |
响应体参数
参数 | 类型 | 描述 |
---|---|---|
userid | String | 设置禁言的 ID。 |
chat | Int | 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。 * > 0 :该用户 ID 具体的单聊消息禁言时长。 * 0 :该用户的单聊消息禁言已取消。* -1 :该用户被设置永久单聊消息禁言。 |
groupchat | Int | 群组消息剩余禁言时长,单位为秒,规则同上。 |
chatroom | Int | 聊天室消息剩余禁言时长,单位为秒,规则同上。 |
unixtime | Int | 当前操作的 Unix 时间戳。 |
请求示例
curl -L -X GET 'https://a1.easemob.com/easemob-demo/testappkey/mutes/zs1' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json'
响应示例
{
"path": "/mutes",
"uri": "https://a1.easemob.com/easemob-demo/testappkey/mutes",
"timestamp": 1631609831800,
"organization": "easemob-demo",
"application": "357169f0-492a-11e9-9b3a-f1af649cc48d",
"action": "get",
"data": {
"userid": "easemob-demo#restys_zs1",
"chat": 96,
"groupchat": 96,
"chatroom": 96,
"unixtime": 1631609831
},
"duration": 13,
"applicationName": "testappkey"
}
查询 app 下的所有全局禁言的用户
该方法查询 app 下所有全局禁言的用户及其禁言剩余时间。
基本信息
方法:GET
接入点: https://{host}/{orgName}/{appName}/mutes
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
orgName | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
appName | String | 必需 | 您在环信管理后台创建的 APP 名称。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Authorization | String | 必需 | 鉴权 token,管理员 token(含)以上权限。 |
请求体参数
参数 | 类型 | 是否必需 | 说明描述 |
---|---|---|---|
pageNum | Int | 必需 | 请求查询的页码。 |
pageSize | Int | 必需 | 请求查询每页显示的禁言用户的数量。 |
响应体参数
参数 | 类型 | 描述 |
---|---|---|
username | String | 设置禁言的用户 ID。 |
chat | Int | 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。 * > 0 :该用户 ID 具体的单聊消息禁言时长。 * 0 :该用户的单聊消息禁言已取消。* -1 :该用户被设置永久单聊消息禁言。 |
groupchat | Int | 群组消息剩余禁言时长,单位为秒,规则同上。 |
chatroom | Int | 聊天室消息剩余禁言时长,单位为秒,规则同上。 |
unixtime | Int | 当前操作的 Unix 时间戳。 |
请求示例
curl -L -X GET 'https://a1.easemob.com/easemob-demo/testappkey/mutes?pageNum=1&pageSize=10' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json'
响应示例
{
"path": "/mutes",
"uri": "https://a1.easemob.com/easemob-demo/testappkey/mutes",
"timestamp": 1631609858771,
"organization": "easemob-demo",
"application": "357169f0-492a-11e9-9b3a-f1af649cc48d",
"action": "get",
"data": {
"data": [
{
"username": "zs2",
"chatroom": 0
},
{
"username": "zs1",
"groupchat": 69
},
{
"username": "zs1",
"chat": 69
},
{
"username": "zs1",
"chatroom": 69
},
{
"username": "h2",
"chatroom": 0
},
{
"username": "h2",
"groupchat": 0
},
{
"username": "h2",
"chat": 0
}
],
"unixtime": 1631609858
},
"duration": 17,
"applicationName": "testappkey"
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求参数错误,请根据返回提示检查。 |
401 | 用户权限错误。 |
403 | 服务未开通或权限不足。 |
429 | 单位时间内请求过多。 |
500 | 服务器内部错误。 |