聊天室黑名单管理

大约 12 分钟

聊天室黑名单管理

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

前提条件

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

公共参数

请求参数

参数类型是否必需描述
hostString是即时通讯 IM 分配的用于访问 RESTful API 的域名。
app_idString是声网为每个项目自动分配的 App ID，作为项目唯一标识。
chatroom_idString是聊天室 ID。
usernameString是用户 ID。
nameString是聊天室名称，最大长度为 128 个字符。
descriptionString是聊天室描述，最大长度为 512 个字符。
maxusersInt否聊天室成员数上限，创建聊天室时设置。该参数的默认最大值为 10,000，如需调整请联系商务。

响应参数

参数类型描述
actionString请求方法。
hostString即时通讯 IM 分配的用于访问 RESTful API 的域名，与请求参数 host 相同。
uriString请求 URL。
pathString请求路径，属于请求 URL 的一部分，开发者无需关注。
idString聊天室 ID，聊天室唯一标识，由即时通讯 IM 服务器生成。
entitiesJSON响应实体。
dataJSON数据详情。
createdString用户、群组或聊天室的创建时间，Unix 时间戳，单位为毫秒。
usernameString用户 ID。
affiliations_countInt聊天室现有成员总数。
affiliationsArray聊天室现有成员列表，数组类型，包含 owner 和 member 元素，即聊天室所有者和聊天室成员（包括聊天室管理员）。例如："affiliations":[{"owner": "13800138001"},{"member":"v3y0kf9arx"},{"member":"xc6xrnbzci"}]。
ownerString聊天室所有者的用户 ID。例如：{"owner": "13800138001"}。
memberString聊天室成员的用户 ID，包括聊天室管理员和普通成员的用户 ID。例如：{"member":"xc6xrnbzci"}。
timestampLongHTTP 响应的 Unix 时间戳，单位为毫秒。
durationLong从发送 HTTP 请求到响应的时长，单位为毫秒。

认证方式

即时通讯 IM 的 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization: Bearer YourAppToken

为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 IM RESTful API 推荐使用 app token 的 鉴权方式，详见使用 Token 鉴权。

添加单个聊天室成员

向聊天室添加一个成员。如果待添加的用户在 app 中不存在或已经在聊天室中，则请求失败并返回错误码 400。

HTTP 请求

POST https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users/{username}
路径参数
参数类型是否必需描述
usernameString是要加入聊天室黑名单的用户 ID。

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

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

HTTP 响应

响应 body

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

参数类型描述
data.resultBool是否添加成功：
- true：是；
- false：否。
data.actionString执行的操作，add_member 表示向聊天室添加成员。
data.idString聊天室 ID，聊天室唯一标识符，由即时通讯 IM 服务器生成。
data.userString添加到聊天室的用户。

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

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

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

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatrooms/66XXXX33/users/user1'
响应示例
{
  "action": "post",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_member",
    "id": "66XXXX33",
    "user": "user1"
  },
  "timestamp": 1542554038353,
  "duration": 0
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!聊天室 ID 不存在。传入存在的合法的聊天室 ID。
404resource_not_foundusername XXX doesn't exist!要添加的用户 ID 不存在。传入存在的用户 ID。
403forbidden_opcan not join this group, reason:user XXX has joined too many chatrooms!要添加的用户已加入了太多的聊天室。传入其他用户 ID。

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

批量添加聊天室成员

向聊天室添加多位用户，一次性最多可添加 60 位用户。

HTTP 请求

POST https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users
路径参数

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
usernamesArray是添加的用户 ID 数组，每次最多可传 60 个用户 ID。

HTTP 响应

响应 body

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

参数类型描述
data.newmembersArray添加成功的用户 ID 数组。
data.actionString执行的操作内容。在该响应中，该字段的值为 add_member，表示添加用户。
data.idString聊天室 ID。

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

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "usernames": [
     "user1","user2"
   ]
 }' 'https://XXXX/app-id/XXXX/chatrooms/66XXXX33/users'
响应示例
{
  "action": "post",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users",
  "entities": [],
  "data": {
    "newmembers": ["user1", "user2"],
    "action": "add_member",
    "id": "66XXXX33"
  },
  "timestamp": 1542554537237,
  "duration": 9
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400invalid_parameteraddMembers: addMembers number more than maxSize : 60批量添加数量达到限制（60）。将添加的成员数量调整在限制（60）以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!聊天室 ID 不存在。传入存在的合法的聊天室 ID。
404resource_not_foundusername XXX doesn't exist!要添加的用户 ID 不存在。传入存在的用户 ID。
403forbidden_opcan not join this group, reason:user XXX has joined too many chatrooms!要添加的用户已加入了太多的聊天室。传入其他用户 ID。

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

移除单个聊天室成员

从聊天室移除一个成员。如果被移除用户不在聊天室中或聊天室不存在，将返回错误。

HTTP 请求

DELETE https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users/{username}
路径参数
参数类型是否必需描述
usernameString是要移出聊天室黑名单的用户 ID。

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

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

HTTP 响应

响应 body

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

参数类型描述
data.resultBool是否成功移出聊天室成员：
- true：是；
- false：否。
data.actionString执行的操作。在该响应中，该字段的值为 remove_member，表示移除聊天室成员。
data.userString用户 ID。
data.idString聊天室 ID。

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

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatrooms/66XXXX33/users/user1'
响应示例
{
  "action": "delete",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_member",
    "user": "user1",
    "id": "66XXXX33"
  },
  "timestamp": 1542555744726,
  "duration": 1
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
400forbidden_opusers [XX] are not members of this group!用户不在聊天室中。传入聊天室中成员的用户 ID。
404resource_not_foundgrpID XX does not exist!聊天室 ID 不存在。传入存在的合法的聊天室 ID。
404resource_not_foundusername XXX doesn't exist!要删除的用户 ID 不存在。传入聊天室中成员的用户 ID。

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

批量移除聊天室成员

从聊天室移除多个成员，单次请求最多可移除 100 个成员。如果被移除用户不在聊天室中或聊天室不存在，将返回错误。

HTTP 请求

DELETE https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users/{usernames}
路径参数
参数类型是否必需描述
usernameString是要移除的一个或多个用户 ID。每次最多可传 100 个用户 ID，用户 ID 之间用英文逗号（","）分隔，逗号在 URL 中转义为 "%2C"。

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

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

HTTP 响应

响应 body

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

参数类型描述
dataJSON Array响应数据。
- resultBool是否成功批量移除聊天室成员：
- true：是；
- false：否。
- actionString执行的操作。在该响应中，该字段的值为 remove_member，表示移除成员。
- reasonString移除失败的原因。
- userString已删除成员的用户 ID 列表。
- idString聊天室 ID。

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

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/chatrooms/66XXXX33/users/user1%2Cuser2'
响应示例
{
  "action": "delete",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1%2Cuser2",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "remove_member",
      "reason": "user: user1 doesn't exist in group: 66XXXX33",
      "user": "user1",
      "id": "66XXXX33"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user2",
      "id": "66XXXX33"
    }
  ],
  "timestamp": 1542556177147,
  "duration": 0
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400invalid_parameterkickMember: kickMembers number more than maxSize : 60批量删除数量达到限制（60）。将传入的成员数量调整到限制（60）以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
400forbidden_opusers [XX] are not members of this group!用户不在聊天室中。传入聊天室中成员的用户 ID。
404resource_not_foundgrpID XX does not exist!聊天室 ID 不存在。传入存在的合法的聊天室 ID。
404resource_not_foundusername XXX doesn't exist!要删除的用户 ID 不存在。传入聊天室中成员的用户 ID。

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

获取聊天室管理员列表

获取聊天室管理员列表的接口。

HTTP 请求

GET https://{host}/app-id/{app_id}/chatrooms/{chatroom_id}/admin
路径参数

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

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

HTTP 响应

响应 body

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

参数类型描述
dataArray聊天室管理员用户 ID 数组。

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

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

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

curl -X GET https://XXXX/app-id/XXXX/chatrooms/12XXXX11/admin -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin",
  "entities": [],
  "data": ["user1"],
  "timestamp": 1489073361210,
  "duration": 0,
  "count": 1
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!聊天室 ID 不存在。传入存在的合法的聊天室 ID。

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

上次编辑于: