用户全局禁言

更新时间: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

路径参数

参数 类型 是否必需描述
orgNameString必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
appNameString必需 您在环信管理后台创建的 APP 名称。

请求参数说明

字段 类型 是否必需字段说明
username string 必需 设置禁言配置的用户 ID。
chat integer非必需 单聊消息禁言时长,单位为秒,最大值为 2147483647。
* > 0:该用户 ID 具体的单聊消息禁言时长。
* 0:取消该用户的单聊消息禁言。
* -1:该用户被设置永久单聊消息禁言。
* 如果设为其他负值,则取值无效。
groupchatinteger非必需 群组消息禁言时长,单位为秒,规则同上。
chatroom integer非必需 聊天室消息禁言时长,单位为秒,规则同上。

请求头

参数 类型 是否必需描述
AuthorizationString必需 鉴权 token,管理员 token(含)以上权限。

响应体参数

参数 类型 描述
resultString该方法调用结果。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"
}

查询单个用户的单聊/群聊/聊天室消息禁言。

基本信息

方法:GET

接入点:https://{host}/{orgName}/{appName}/mutes/username

路径参数

参数 类型 是否必需描述
orgName String必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
appName String必需 您在环信管理后台创建的 APP 名称。
usernameString必需 查询禁言信息的用户 ID。

请求头参数

参数 类型 是否必需描述
Content-Type String必需 application/json 内容类型。
AuthorizationString必需 鉴权 token,管理员 token (含)以上权限。

响应体参数

参数 类型 描述
userid String设置禁言的 ID。
chat Int 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。
* > 0:该用户 ID 具体的单聊消息禁言时长。
* 0:该用户的单聊消息禁言已取消。
* -1:该用户被设置永久单聊消息禁言。
groupchatInt 群组消息剩余禁言时长,单位为秒,规则同上。
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 下所有全局禁言的用户及其禁言剩余时间。

基本信息

方法:GET

接入点: https://{host}/{orgName}/{appName}/mutes

路径参数

参数 类型 是否必需描述
orgNameString必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
appNameString必需 您在环信管理后台创建的 APP 名称。

请求头参数

参数 类型 是否必需描述
AuthorizationString必需 鉴权 token,管理员 token(含)以上权限。

请求体参数

参数 类型 是否必需说明描述
pageNum Int必需 请求查询的页码。
pageSizeInt必需 请求查询每页显示的禁言用户的数量。

响应体参数

参数 类型 描述
username String设置禁言的用户 ID。
chat Int 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。
* > 0:该用户 ID 具体的单聊消息禁言时长。
* 0:该用户的单聊消息禁言已取消。
* -1:该用户被设置永久单聊消息禁言。
groupchatInt 群组消息剩余禁言时长,单位为秒,规则同上。
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服务器内部错误。