文档中心





即时通讯 (环信)

Console 官网社区技术支持





管理群组黑名单

更新时间 2023/05/06 08:27:45

群组黑名单是指群组中无法查看和接收群组消息的用户列表。即时通讯 IM 提供多个接口实现群组黑名单管理，包括查看黑名单中的用户以及将用户加入和移除黑名单等。

调用本文中的 API 前，请先参考使用限制了解即时通讯 RESTful API 的调用频率限制。

公共参数

以下表格列举了即时通讯 RESTful API 的公共请求参数和响应参数。

请求参数

参数	类型	描述	是否必填
`host`	String	即时通讯服务分配的 RESTful API 访问域名。你可以通过声网控制台获取该字段，详见获取即时通讯项目信息。	是
`org_name`	String	即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过声网控制台获取该字段，详见获取即时通讯项目信息。	是
`app_name`	String	即时通讯服务分配给每个 app 的唯一标识。你可以通过声网控制台获取该字段，详见获取即时通讯项目信息。	是
`username`	String	用户 ID。用户的唯一登录账号。	是

响应参数

参数	类型	描述
`action`	String	请求方式。
`organization`	String	组织 ID，即时通讯服务分配给每个企业（组织）的唯一标识，与请求参数 `org_name` 相同。
`application`	String	系统内为 app 生成的唯一内部标识，无需关注。
`applicationName`	String	App ID，即时通讯服务分配给每个 app 的唯一标识，与请求参数 `app_name` 相同。
`entities`	JSON	返回实体信息。
`timestamp`	Number	响应的 Unix 时间戳，单位为毫秒。
`duration`	Number	从发送请求到响应的时长，单位为毫秒。

认证方式

即时通讯 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?pageSize={N}&cursor={cursor}

路径参数

参数及描述详见公共参数。

查询参数

参数	类型	是否必需	描述
`pageSize`	Number	否	每次期望返回的黑名单用户的数量。取值范围为 [1,50]。该参数仅在分页获取时为必需。
`cursor`	String	否	数据查询的起始位置。该参数仅在分页获取时为必需。

如果 pageSize 和 cursor 参数均不传，获取最新加入群组黑名单的 500 个用户。若只传 pageSize 而不传 cursor，服务器返回第一页黑名单用户列表，即最新加入黑名单的用户，最多不超过 50 个。

参数	类型	是否必需	描述
`Accept`	String	是	内容类型。请填 `application/json`。
`Authorization`	String	是	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段	类型	描述
`cursor`	String	查询游标，指定下次查询的起始位置。
`count`	Number	群组黑名单中的用户数量。
`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?pageSize=2'

响应示例

{
    "uri": " https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/blocks/users",
    "timestamp": 1682064422108,
    "entities": [],
    "cursor": "MTA5OTAwMzMwNDUzNTA2ODY1NA==",
    "count": 2,
    "action": "get",
    "data": [
        "tst05",
        "tst04"
    ],
    "duration": 52
}

添加单个用户至群组黑名单

将单个用户添加至群组黑名单。群主无法被加入群组的黑名单。

用户进入群组黑名单后会收到加入黑名单的回调。之后，该用户无法查看该群组的信息，也收不到该群组的消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}

路径参数

参数	类型	描述	是否必需
`group_id`	String	群组 ID。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。填入 `application/json`。	是
`Accept`	String	内容类型。填入 `application/json`。	是
`Authorization`	String	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app 权限 token。	是

HTTP 响应

响应 body

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

参数	类型	描述
`data`	JSON	将用户添加到群组黑名单的结果。
`data.result`	Boolean	是否成功将指定用户添加到群组黑名单： `true`：是 `false`：否
`data.groupid`	String	群组 ID。
`data.action`	String	执行操作。在该响应中，`add_blocks` 表示将用户添加到群组黑名单。
`data.user`	String	添加到群组黑名单的用户 ID。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码不是 200，则表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1'

响应示例

{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1",
    "entities": [],
    "data": {
      "result": true,
      "action": "add_blocks",
      "user": "user1",
      "groupid": "66016455491585"
    },
    "timestamp": 1542539577124,
    "duration": 27,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

批量添加用户至群组黑名单

将多个用户添加至群组黑名单，一次最多可以添加 60 个用户。群主无法被加入群组的黑名单。

用户进入群组黑名单后会收到加入黑名单的回调。黑名单上的用户无法查看该群组的信息，也收不到该群组的消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users

路径参数

参数	类型	描述	是否必需
`group_id`	String	群组 ID。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。填入 `application/json`。	是
`Accept`	String	内容类型。填入 `application/json`。	是
`Authorization`	String	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app 权限 token。	是

请求 body

参数	类型	描述	是否必须
`usernames`	Array	待添加至群组黑名单中的用户 ID。	是

HTTP 响应

响应 body

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

参数	类型	描述
`data`	JSON Array	添加结果。
`data.result`	Boolean	是否成功将指定用户添加至群组黑名单： `true`：是 `false`：否
`data.reason`	String	用户未能添加至群组黑名单的原因。
`data.groupid`	String	群组 ID。
`data.action`	String	执行操作。在该响应中，`add_blocks` 表示将成员添加至群组黑名单。
`data.user`	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"
    ]
}' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users'

响应示例

{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users",
    "entities": [],
    "data": [
      {
        "result": false,
        "action": "add_blocks",
        "reason": "user: user3 doesn't exist in group: 66016455491585",
        "user": "user3",
        "groupid": "66016455491585"
      },
      {
        "result": true,
        "action": "add_blocks",
        "user": "user4",
        "groupid": "66016455491585"
      }
    ],
    "timestamp": 1542540095540,
    "duration": 16,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

从群组黑名单移除单个用户

将单个用户移出群组黑名单。对于群组黑名单中的用户，如果需要将其再次加入群组，需要先将其从群组黑名单中移除。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}

路径参数

参数	类型	描述	是否必需
`group_id`	String	群组 ID。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Accept`	String	内容类型。填入 `application/json`。	是
`Authorization`	String	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app 权限 token。	是

HTTP 响应

响应 body

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

参数	类型	描述
`data`	JSON	移除结果。
`data.result`	Boolean	是否成功将指定用户移出群组黑名单： `true`：是 `false`：否
`data.groupid`	String	群组 ID。
`data.action`	String	执行操作。在该响应中，`remove_blocks` 表示将用户移出群组黑名单。
`data.user`	String	从群组黑名单移除的用户 ID。

其他字段及描述详见公共参数。

如果返回的 HTTP 状态码不是 200，则表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1'

响应示例

{
    "action": "delete",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1",
    "entities": [],
    "data": {
      "result": true,
      "action": "remove_blocks",
      "user": "user1",
      "groupid": "66016455491585"
    },
    "timestamp": 1542540470679,
    "duration": 45,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

从群组黑名单批量移除用户

将多名指定用户从群组黑名单中移除。对于群组黑名单中的用户，如果需要将其再次加入群组，需要先将其从群组黑名单中移除。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{usernames}

路径参数

参数	类型	描述	是否必需
`group_id`	String	群组 ID。	是
`usernames`	String	要移除群组黑名单的用户 ID。多个用户 ID 之间使用英文逗号隔开。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Accept`	String	内容类型。填入 `application/json`。	是
`Authorization`	String	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app 权限 token。	是

HTTP 响应

响应 body

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

参数	类型	描述
`data`	JSON Array	批量移除结果。
`data.result`	Boolean	是否成功将指定用户移出群组黑名单： `true`：是 `false`：否
`data.groupid`	String	群组 ID。
`data.action`	String	执行操作。在该响应中，`remove_blocks` 表示将用户移出群组黑名单。
`data.user`	String	从群组黑名单批量移除的用户 ID。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码不是 200，则表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1%2Cuser2'

响应示例

{
    "action": "delete",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://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": "XXXX"
}

状态码

详见 HTTP 状态码。

这篇文章对你有帮助吗？

是

否