管理群组主和群管理员

大约 9 分钟

管理群组主和群管理员

环信即时通讯 IM 提供了多个 RESTful API 管理群主和管理员,包括转让群组、查询管理员和添加和移除单个群组管理员。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

公共参数

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息
group_idString群组 ID。

响应参数

参数类型描述
actionString请求方法。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
entitiesJSON响应实体。
dataJSON实际获取的数据详情。
createdLong群组创建时间,Unix 时间戳,单位为毫秒。
timestampLongUnix 时间戳,单位为毫秒。
durationInt从发送请求到响应的时长,单位为毫秒。
propertiesString响应属性。

群组角色

群组角色包含群主、群管理员和普通群成员,三个角色权限范围依次递减。

  • 群主拥有群的所有权限;
  • 群管理员拥有管理黑名单、白名单和禁言等权限;
  • 群主加管理员数量共 100 个,即管理员最多可添加 99 个。

认证方式

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式,详见 使用 App Token 鉴权

转让群组

修改群主为同一群组中的其他成员。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/chatgroups/{group_id}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型描述
newownerString群组的新群主的用户 ID。

HTTP 响应

响应 body

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

字段类型描述
data.newownerBool操作结果:
- true:转让成功。
- false:转让失败。

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

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

示例

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

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{ "newowner": "user2" }' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85'
响应示例
{
  "action": "put",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85",
  "entities": [],
  "data": {
    "newowner": true
  },
  "timestamp": 1542537813420,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opuser: XX doesn't exist in group: XXX要转让的新群主不在群组中。传入群组成员的用户 ID。
403forbidden_opnew owner and old owner are the same新群主和旧群主不能是同一群成员。传入的新群主的用户 ID 不能与旧群主的用户 ID 相同。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

获取群管理员列表

获取群组管理员列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/admin
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
dataArray群组管理员的用户 ID 列表。

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

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

示例

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

curl -X GET HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/admin -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/admin",
  "entities": [],
  "data": ["user1"],
  "timestamp": 1489073361210,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 1
}

错误码

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

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

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

添加群管理员

将一个普通群成员设为群管理员。群管理员有管理黑名单、禁言等权限。最多可以添加 99 个群管理员。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/admin
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
newadminString要添加的新管理员的用户 ID。

HTTP 响应

响应 body

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

字段类型描述
dataJSON群管理员添加结果。
data.resultString群管理员是否添加成功。
data.newadminString添加的管理员的用户 ID。

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

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

示例

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

curl -X POST HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/admin -d '{"newadmin":"user1"}' -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "post",
  "application": "52XXXXf0",
  "applicationName": "demo",
  "data": {
    "result": "success",
    "newadmin": "man"
  },
  "duration": 0,
  "entities": [],
  "organization": "XXXX",
  "properties": {},
  "timestamp": 1680074570600,
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/190141728620545/admin"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
404resource_not_founduser: XX doesn't exist in group: XXX用户不在群组中。传入群组成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

移除群管理员

将用户的角色从群管理员降为群普通成员。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/admin/{username}
路径参数
参数类型是否必需描述
usernameString要移出群组管理员列表的管理员的用户 ID。

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
data.resultBool操作结果:
- success:表示移除成功;
- failure:表示移除失败。
data.oldadminString被移除的管理员用户 ID。

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

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

示例

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

curl -X DELETE HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/admin/user1 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/admin/user1",
  "entities": [],
  "data": {
    "result": "success",
    "oldadmin": "user1"
  },
  "timestamp": 1489073432732,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opuser:XX is not admin of group:XX用户不是这个群的管理员。传入在群组中管理员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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