添加/移除群组成员

大约 11 分钟

添加/移除群组成员

环信即时通讯 IM 提供了多个 RESTful API 接口实现群组成员的添加和移除,包括添加单个或批量添加成员和移除单个或批量移除成员。

前提条件

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

公共参数

请求参数

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

响应参数

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

认证方式

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

Authorization: Bearer YourAppToken

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

添加单个群组成员

每次添加一个群成员。若添加的用户已是群成员,则添加失败,返回错误。

HTTP 请求

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

参数及描述详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
data.resultBool添加结果:
- true:成功。
- false:失败。
data.groupidString群组 ID。
data.actionString执行的操作。在该响应中,该字段的值为 add_member,表示添加群组成员。
data.userString添加的用户 ID。

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

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

示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/user4'
响应示例
{
  "action": "post",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/user4",
  "entities": [],
  "data": {
    "result": true,
    "groupid": "66XXXX85",
    "action": "add_member",
    "user": "user4"
  },
  "timestamp": 1542364958405,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opcan not join this group, reason:user: XX already in group: XX\n用户已经在群里。不要重复加入。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
404resource_not_foundusername XX doesn't exist!要添加的用户不存在使用合法的用户,即 username 传入存在的用户 ID。
403exceed_limituser XX has joined too many groups!用户可加入的群组数达到上限。退出不用的群组或联系商务调整上限。

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

批量添加群组成员

一次为群组添加多个成员,每次最多可以添加 60 位成员。如果所有用户均已是群成员,添加失败,返回错误。

HTTP 请求

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

参数及描述详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
data.newmembersArray添加的群组成员的用户 ID。
data.groupidString群组 ID。
data.actionString执行的操作。在该响应中,该字段的值为 add_member,表示添加群成员。

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

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

示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "usernames": [
     "user4","user5"
   ]
 }' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users'
响应示例
{
  "action": "post",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users",
  "entities": [],
  "data": {
    "newmembers": ["user5", "user4"],
    "groupid": "66XXXX85",
    "action": "add_member"
  },
  "timestamp": 1542365557942,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opan not join this group, reason:user: XX already in group: XX\n用户已经在群里。不要重复加入。
403exceed_limituser XX has joined too many groups!用户可加入的群组数达到上限。退出不用的群组或联系商务调整上限。
403exceed_limitmembers size is greater than max user size !加入群成员的人数超过最大限制。每次最多可以添加 60 位成员。调整创建群的加群人数。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
404resource_not_foundusername XX doesn't exist!要添加的用户不存在。使用合法的用户,即 username 传入存在的用户 ID。

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

移除单个群组成员

从群中移除指定成员。如果被移除用户不是群成员,将移除失败,并返回错误。移除后,该成员也会被移除其在该群组中加入的子区。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/users/{username}
路径参数

参数及描述详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
data.resultBool移除结果:
- true:移除成功;
- false:移除失败。
data.groupidString群组 ID。
data.actionString执行的操作。在该响应中,该字段的值为 remove_member,表示移除群组成员。
data.userString被移除的用户 ID。

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

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

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/user3'
响应示例
{
  "action": "delete",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/user3",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_member",
    "user": "user3",
    "groupid": "66XXXX85"
  },
  "timestamp": 1542365943067,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!用户不在群组中。传入群组中成员的用户 ID。
403forbidden_opforbidden operation on group owner!群主不能被移除。不要将群主移出群组。
403exceed_limituser XX has joined too many groups!用户加入的群组数达到上限。退出不用的群组或联系商务调整上限。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

批量移除群组成员

一次移除多名群成员。如果所有被移除用户均不是群成员,将移除失败,并返回错误。移除后,这些成员也会被移除其在该群组中加入的子区。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/users/{members}
路径参数
参数类型是否必需描述
membersString要移除的群成员的用户 ID,用户 ID 之间用英文逗号(",")分隔。建议每次最多传 60 个用户 ID,并且 URL 的长度不超过 4 KB。

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

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- resultBool操作结果:
- true:移除成功;
- false:移除失败。
- actionString执行的操作。在该响应中,该字段的值为 remove_member,表示移除群组成员。
- reasonString操作失败的原因。
- userString被移除成员的用户 ID。
- groupidString操作的群组 ID。

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

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

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/ttXXXX81,user2,user3'
响应示例
{
  "action": "delete",
  "application": "9bXXXXf7",
  "uri": "https://XXXX/XXXX/XXXX",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "remove_member",
      "reason": "user ttXXXX81 doesn't exist.",
      "user": "user1",
      "groupid": "14XXXX79"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user2",
      "groupid": "14XXXX79"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user3",
      "groupid": "14XXXX79"
    }
  ],
  "timestamp": 1433492935318,
  "duration": 84,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!用户不在群组中。传入群组中成员的用户 ID。
403forbidden_opforbidden operation on group owner!群主不能被移除。无。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
400invalid_parameterkickMember: kickMembers number more than maxSize : 60批量移除群成员数量超过 60 人。控制批量移除群成员数量在 60 以内。

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