群组黑名单管理

大约 11 分钟

群组黑名单管理

即时通讯 IM 提供多个接口实现群组黑名单管理，包括查询群组黑名单、将成员添加和移除聊天室黑名单。

前提条件

要调用即时通讯 RESTful API，请确保满足以下要求：

已在声网控制台open in new window 开通配置即时通讯 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}/blocks/users

路径参数

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

参数	类型	是否必需	描述
`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/app-id/XXXX/chatgroups/66XXXX85/blocks/users'

响应示例

{
  "action": "get",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/67178793598977/blocks/users",
  "entities": [],
  "data": ["user2", "user3"],
  "timestamp": 1543466293681,
  "duration": 0,
  "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}/app-id/{app_id}/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/app-id/XXXX/chatgroups/66XXXX85/blocks/users/user1'

响应示例

{
  "action": "post",
  "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
}

错误码

如果返回的 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}/app-id/{app_id}/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/app-id/XXXX/chatgroups/66XXXX85/blocks/users'

响应示例

{
  "action": "post",
  "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
}

错误码

如果返回的 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}/app-id/{app_id}/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/app-id/XXXX/chatgroups/66XXXX85/blocks/users/user1'

响应示例

{
  "action": "delete",
  "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
}

错误码

如果返回的 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}/app-id/{app_id}/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/app-id/XXXX/chatgroups/66XXXX85/blocks/users/user1%2Cuser2'

响应示例

{
  "action": "delete",
  "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
}

错误码

如果返回的 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。

关于其他错误，你可以参考响应状态码了解可能的原因。

群组黑名单管理

# 群组黑名单管理

# 前提条件

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 查询群组黑名单

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

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

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

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

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

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

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

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

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

群组黑名单管理

前提条件

公共参数

请求参数

响应参数

认证方式

查询群组黑名单

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

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

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

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

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

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

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

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

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码