群成员管理

环信即时通讯 IM 提供了 RESTful API 管理 App 中群组的成员，包括添加和移除群组成员、转让群组所有权以及群组黑名单、白名单和禁言列表相关操作。

前提条件

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

• 已在环信即时通讯 IM 管理后台 开通配置环信即时通讯 IM 服务。
• 了解环信 IM RESTful API 的调用频率限制，详见 接口频率限制。
• 群成员的相关限制，详见 使用限制。

公共参数

请求参数

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

响应参数

参数	类型	描述
action	String	请求方法。
organization	String	环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 org_name 相同。
application	String	应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。
applicationName	String	你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 app_name 相同。
uri	String	请求 URL。
path	String	请求路径，属于请求 URL 的一部分，开发者无需关注。
entities	JSON	响应实体。
data	JSON	实际获取的数据详情。
uuid	String	用户在系统内的唯一标识。该标识由系统生成，开发者无需关心。
created	Long	群组创建时间，Unix 时间戳，单位为毫秒。
timestamp	Long	Unix 时间戳，单位为毫秒。
duration	Int	从发送请求到响应的时长，单位为毫秒。
properties	String	响应属性。

群组角色

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

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

认证方式

环信即时通讯 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}/users?pagenum={N}&pagesize={N}

路径参数

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

查询参数

参数	类型	是否必需	描述
pagenum	Int	否	当前页码。默认从第 1 页开始获取。
pagesize	Int	否	每页期望返回的群组成员数量。取值范围为 [1,1000]。默认为 1000。若传入的值大于 1000，则获取 1000 个群组成员。

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data.owner	String	群主的用户 ID。例如：{“owner”: “user1”}。
data.member	String	普通群成员或群管理员的用户 ID。例如：{“member”:“user2”}。
count	Number	本次调用获取的群成员数量。

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

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

示例

请求示例

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

curl -X GET HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/users?pagenum=2&pagesize=2 -H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "action": "get",
  "application": "52XXXXf0",
  "params": {
    "pagesize": ["2"],
    "pagenum": ["2"]
  },
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/users",
  "entities": [],
  "data": [
    {
      "owner": "user1"
    },
    {
      "member": "user2"
    }
  ],
  "timestamp": 1489074511416,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 2
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
404	service_resource_not_found	do not find this group:XX	群组不存在。	使用合法的群 ID。

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

添加单个群组成员

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/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.groupid	String	群组 ID。
data.action	String	执行的操作。在该响应中，该字段的值为 add_member，表示添加群组成员。
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>' '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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	can not join this group, reason:user: XX already in group: XX\n	用户已经在群里。	不要重复加入。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。
404	resource_not_found	username XX doesn't exist!	要添加的用户不存在	使用合法的用户，即 username 传入存在的用户 ID。
403	exceed_limit	user XX has joined too many groups!	用户可加入的群组数达到上限。	退出不用的群组或联系商务调整上限。

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

批量添加群组成员

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/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.newmembers	Array	添加的群组成员的用户 ID。
data.groupid	String	群组 ID。
data.action	String	执行的操作。在该响应中，该字段的值为 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	an not join this group, reason:user: XX already in group: XX\n	用户已经在群里。	不要重复加入。
403	exceed_limit	user XX has joined too many groups!	用户可加入的群组数达到上限。	退出不用的群组或联系商务调整上限。
403	exceed_limit	members size is greater than max user size !	加入群成员的人数超过最大限制。每次最多可以添加 60 位成员。	调整创建群的加群人数。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。
404	resource_not_found	username XX doesn't exist!	要添加的用户不存在。	使用合法的用户，即 username 传入存在的用户 ID。

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

移除单个群组成员

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

HTTP 请求

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

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data.result	Bool	移除结果： - true：移除成功； - false：移除失败。
data.groupid	String	群组 ID。
data.action	String	执行的操作。在该响应中，该字段的值为 remove_member，表示移除群组成员。
data.user	String	被移除的用户 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	users [XX] are not members of this group!	用户不在群组中。	传入群组中成员的用户 ID。
403	forbidden_op	forbidden operation on group owner!	群主不能被移除。	不要将群主移出群组。
403	exceed_limit	user XX has joined too many groups!	用户加入的群组数达到上限。	退出不用的群组或联系商务调整上限。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。

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

批量移除群组成员

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

HTTP 请求

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

路径参数

参数	类型	是否必需	描述
members	String	是	要移除的群成员的用户 ID，用户 ID 之间用英文逗号（","）分隔。建议每次最多传 60 个用户 ID，并且 URL 的长度不超过 4 KB。

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

请求 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_member，表示移除群组成员。
- reason	String	操作失败的原因。
- user	String	被移除成员的用户 ID。
- groupid	String	操作的群组 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	users [XX] are not members of this group!	用户不在群组中。	传入群组中成员的用户 ID。
403	forbidden_op	forbidden operation on group owner!	群主不能被移除。	无。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。
400	invalid_parameter	kickMember: kickMembers number more than maxSize : 60	批量移除群成员数量超过 60 人。	控制批量移除群成员数量在 60 以内。

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

设置群成员自定义属性

群成员可设置自定义属性（key-value），例如在群组中的昵称和头像等。

群主可修改所有群成员的自定义属性，其他群成员只能修改自己的自定义属性。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/user/{username}

路径参数

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

请求 header

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

请求 body

参数	类型	是否必需	描述
metaData	JSON	是	要设置的群成员自定义属性，为 key-value 键值对。对于单个键值对： - key 表示属性名称，不能超过 16 字节。 - value 表示属性值，不能超过 512 个字节。若 value 设置为空字符串即删除该自定义属性。 注意 单个群成员的自定义属性总长度不能超过 4 KB。

HTTP 响应

响应 body

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

字段	类型	描述
data	JSON	设置的群成员自定义属性。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X PUT 'https://XXXX/XXXX/XXXX/metadata/chatgroup/XXXX/user/XXXX' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "metaData": {
          "key1": "value1"
    }
}'

响应示例

{
  "timestamp": 1678674135533,
  "data": {
    "key1": "value1"
  },
  "duration": 53
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	metadata_error	exceeds chatgroup user metadata single key limit	添加的群成员属性的 key 过长。	调整群成员属性 key 的长度。属性 key 不能超过 16 字节。
400	metadata_error	exceeds chatgroup user metadata single value limit	添加的群成员属性的 value 过长。	调整群成员属性 value 的长度。value 不能超过 512 个字节。
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。

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

获取单个群成员的所有自定义属性

获取单个群成员的所有自定义属性。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/user/{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	JSON	获取的群成员自定义属性。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'https://a1-hsb.easemob.com/easemob-demo/testy/metadata/chatgroup/207059303858177/user/test2' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-H 'Authorization: Bearer YWMtozZwfsFFEe2oQTE6aob5eQAAAAAAAAAAAAAAAAAAAAExCXvf5bRGAJBgXNYFJVQ9AQMAAAGG2MUClwBPGgDsI1GYg1QtapTEdGyrm29Eu6L8qx60lDZ9TJRDOQjEsw' \
--data-raw ''

响应示例

{
  "timestamp": 1678674211840,
  "data": {
    "key1": "value1"
  },
  "duration": 6
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
404	MetadataException	user not in group	用户不在群组内。	使用正确的群组成员的用户 ID。

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

根据属性 key 获取多个群成员的自定义属性

根据指定的属性 key 获取多个群成员的自定义属性。每次最多可获取 10 个群成员的自定义属性。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/get

路径参数

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

请求 header

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

请求 body

参数	类型	是否必需	描述
targets	JSON Array	是	要获取自定义属性的群成员的用户 ID。一次最多可传 10 个用户 ID。
properties	JSON Array	是	要获取自定义属性的 key 的数组。若该参数设置为空数组或不传，则获取这些群成员的所有自定义属性。

HTTP 响应

响应 body

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

字段	类型	描述
data	JSON	获取的群成员的自定义属性。如下响应示例中的 test1 和 test2 为自定义属性所属的群成员的用户 ID。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X POST 'https://XXXX/XXXX/XXXX/metadata/chatgroup/XXXX/get'\
-H'Content-Type: application/json'\
-H'Accept: application/json'\
-H'Authorization: Bearer <YourAppToken>'\
-d '{
    "targets":["test1","test2"],
    "properties":["key1","key2"]
}'

响应示例

{
  "timestamp": 1678674292783,
  "data": {
    "test1": {
      "key1": "value1"
    },
    "test2": {
      "key1": "value1"
    }
  },
  "duration": 2
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	metadata_error	query param reaches limit.	批量查询数量达到限制。	减少要查询的用户 ID。每次最多可获取 10 个群成员的自定义属性。
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。

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

获取群管理员列表

获取群组管理员列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/admin

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data	Array	群组管理员的用户 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。

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

添加群管理员

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/admin

路径参数

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

请求 header

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

请求 body

参数	类型	是否必需	描述
newadmin	String	是	要添加的新管理员的用户 ID。

HTTP 响应

响应 body

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

字段	类型	描述
data	JSON	群管理员添加结果。
data.result	String	群管理员是否添加成功。
data.newadmin	String	添加的管理员的用户 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
404	resource_not_found	user: XX doesn't exist in group: XXX	用户不在群组中。	传入群组成员的用户 ID。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。

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

移除群管理员

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

HTTP 请求

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

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data.result	Bool	操作结果： - success：表示移除成功; - failure：表示移除失败。
data.oldadmin	String	被移除的管理员用户 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	user:XX is not admin of group:XX	用户不是这个群的管理员。	传入在群组中管理员的用户 ID。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。

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

转让群组

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

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/chatgroups/{group_id}

路径参数

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

请求 header

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

请求 body

参数	类型	描述
newowner	String	群组的新群主的用户 ID。

HTTP 响应

响应 body

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

字段	类型	描述
data.newowner	Bool	操作结果： - 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 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
403	forbidden_op	user: XX doesn't exist in group: XXX	要转让的新群主不在群组中。	传入群组成员的用户 ID。
403	forbidden_op	new owner and old owner are the same	新群主和旧群主不能是同一群成员。	传入的新群主的用户 ID 不能与旧群主的用户 ID 相同。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。

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

管理黑名单

环信即时通讯 IM 提供多个接口完成群组黑名单管理，包括查看黑名单中的用户以及将用户加入和移除黑名单等。

查询群组黑名单

查询一个群组黑名单中的用户列表。黑名单中的用户无法查看该群组的信息，也无法收到该群组的消息。

HTTP 请求

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

路径参数

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

请求 header

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

响应示例

{
  "action": "get",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/67178793598977/blocks/users",
  "entities": [],
  "data": ["user2", "user3"],
  "timestamp": 1543466293681,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "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}/{org_name}/{app_name}/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/XXXX/XXXX/chatgroups/66XXXX85/blocks/users/user1'

响应示例

{
  "action": "post",
  "application": "8bXXXX02",
  "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,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

响应示例

{
  "action": "post",
  "application": "8bXXXX02",
  "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,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

响应示例

{
  "action": "delete",
  "application": "8bXXXX02",
  "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,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

响应示例

{
  "action": "delete",
  "application": "8bXXXX02",
  "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,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

管理白名单

环信即时通讯 IM 提供多个接口实现群组白名单管理，包括查看群组白名单中的用户以及将用户添加至或移除白名单等。

查询群组白名单

查询群组白名单中的用户列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/white/users

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data	Array	群组白名单中的用户 ID 列表。

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

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

示例

请求示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/{groupid}/white/users'

响应示例

{
  "action": "get",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users",
  "entities": [],
  "data": [
    "wzy_test", 
    "wzy_vivo", 
    "wzy_huawei", 
    "wzy_xiaomi", 
    "wzXXXXzu"
    ],
  "timestamp": 1594724947117,
  "duration": 3,
  "organization": "XXXX",
  "applicationName": "XXXX",
  "count": 5
}

错误码

如果返回的 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}/{org_name}/{app_name}/chatgroups/{group_id}/white/users/{username}

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	描述
data.result	添加结果： - true：添加成功； - false：添加失败。
data.action	执行操作。在该响应中，该字段的值为 add_user_whitelist，表示将成员加入群白名单。
data.user	添加的用户 ID。
data.groupid	群组 ID。

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

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

示例

请求示例

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

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/{groupid}/white/users/{username}'

响应示例

{
  "action": "post",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users/wzy_xiaomi",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_user_whitelist",
    "user": "wzy_xiaomi",
    "groupid": "12XXXX53"
  },
  "timestamp": 1594724293063,
  "duration": 4,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

错误码

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

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/white/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_user_whitelist，表示将成员加入群白名单。
- user	String	添加的用户 ID。
- groupid	String	群组 ID。
- reason	String	添加失败的原因。

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

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

示例

请求示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{"usernames" : ["user1"]}' 'https://XXXX/XXXX/XXXX/chatgroups/{groupid}/white/users'

响应示例

{
  "action": "post",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "add_user_whitelist",
      "user": "wzy_test",
      "groupid": "12XXXX53"
    },
    {
      "result": true,
      "action": "add_user_whitelist",
      "user": "wzXXXXzu",
      "groupid": "12XXXX53"
    }
  ],
  "timestamp": 1594724634191,
  "duration": 2,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	invalid_parameter	usernames size is more than max limit : 60	批量添加白名单的群成员超过了上限 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。

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

从群组白名单移除用户

将指定用户从群组白名单中移除。你每次最多可移除 60 个用户。

HTTP 请求

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

路径参数

参数	类型	是否必需	描述
username	String	是	要从群组白名单中移除的用户 ID，最多可传 60 个，用户 ID 之间以英文逗号（","）分隔。

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

请求 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_user_whitelist，表示将成员移出群组白名单。
- user	String	移除群组白名单的用户 ID，多个用户 ID 以英文逗号（","）分隔。
- groupid	String	群组 ID。

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

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

示例

请求示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/{groupid}/white/users/{username}'

响应示例

{
  "action": "delete",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/white/users/wzy_huawei,wzXXXXzu",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "remove_user_whitelist",
      "user": "wzy_huawei",
      "groupid": "12XXXX53"
    },
    {
      "result": true,
      "action": "remove_user_whitelist",
      "user": "wzXXXXzu",
      "groupid": "12XXXX53"
    }
  ],
  "timestamp": 1594725137704,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	invalid_parameter	removeWhitelist size is more than max limit : 60	批量移除白名单的群成员数量超过了上限 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。

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

管理禁言

环信即时通讯 IM 提供多个接口进行群组禁言列表管理，包括查看禁言列表以及将用户添加至或移出禁言列表等。

获取禁言列表

获取当前群组的禁言用户列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/mute

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data	JSON Array	响应数据。
- expire	Long	禁言到期的时间，单位为毫秒。
- user	String	被禁言用户的 ID。

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

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

示例

请求示例

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

curl -X GET HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/mute -H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "action": "get",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/mute",
  "entities": [],
  "data": [
    {
      "expire": 1489158589481,
      "user": "user1"
    }
  ],
  "timestamp": 1489072802179,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

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

禁言指定群成员

对一个或多个群成员禁言。你一次最多可禁言 60 个群组成员。

群成员被禁言后，将无法在群组中发送消息，也无法在该群组下的子区中发送消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/mute

路径参数

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

请求 header

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

请求 body

参数	类型	是否必需	描述
mute_duration	Long	是	禁言时长，单位为毫秒。
usernames	Array	是	要添加到禁言列表的用户 ID 列表，每次最多可添加 60 个。

HTTP 响应

响应 body

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

字段	类型	描述
data	JSON Array	响应数据。
- result	Bool	操作结果： - true：添加成功； - false：添加失败。
- expire	Long	禁言到期的时间。该时间为 Unix 时间戳，单位为毫秒。
- user	String	被禁言用户的 ID。

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

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

示例

请求示例

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

curl -X POST HTTP://XXXX/XXXX/XXXX/chatgroups/10XXXX85/mute -d '{"usernames":["user1"], "mute_duration":86400000}' -H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "action": "post",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/mute",
  "entities": [],
  "data": [
    {
      "result": true,
      "expire": 1489158589481,
      "user": "user1"
    }
  ],
  "timestamp": 1489072189508,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

如果返回的 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。
400	invalid_parameter	userNames size is more than max limit : 60	批量禁言指定群成员数量超过60	控制禁言指定群成员数量在 60 以内。
403	forbidden_op	"forbidden operation on group owner!"	无法对群主禁言。

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

禁言全体群成员

对所有群组成员一键禁言，即将群组的所有成员加入禁言列表。设置群组全员禁言后，仅群组白名单中的用户可在群组以及该群组下的子区内发送消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/ban

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data.mute	Bool	操作结果： - true：禁言成功； - false：禁言失败。

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

如果返回的 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/{groupid}/ban'

响应示例

{
  "action": "post",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/ban",
  "entities": [],
  "data": {
    "mute": true
  },
  "timestamp": 1594628861058,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

错误码

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

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

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

解除成员禁言

将一个或多个群成员移出禁言列表。你一次最多可对 60 个成员解除禁言。

移除后，群成员可以在群组中正常发送消息，同时也可以在该群组下的子区中发送消息。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/mute/{member1}(,{member2},…)

路径参数

参数	类型	是否必需	描述
member	String	是	要解除禁言的成员的用户 ID，每次最多可传 60 个，多个用户 ID 之间以英文逗号（","）分隔，例如 {member1},{member2}。

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

请求 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：解除失败。
- user	Array	被移出禁言列表的用户 ID。

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

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

示例

请求示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/10130212061185/mute/user1'

响应示例

{
  "action": "delete",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/10XXXX85/mute/user1",
  "entities": [],
  "data": [
    {
      "result": true,
      "user": "user1"
    }
  ],
  "timestamp": 1489072695859,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。
404	resource_not_found	grpID XX does not exist!	群组不存在。	使用合法的群 ID。
400	invalid_parameter	removeMute member size more than max limit : 60	批量移除禁言列表的用户数超过上限 60。	控制解除成员禁言数量在 60 以内。

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

解除全员禁言

一键取消对群组全体成员的禁言。解除禁言后，群成员可以在群组和该群组下的子区中正常发送消息。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/ban

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
data.mute	Bool	是否处于全员禁言状态。 - true：是； - false：否。

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

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

示例

请求示例

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

curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/{groupid}/ban'

响应示例

{
  "action": "delete",
  "application": "XXXX",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/12XXXX53/ban",
  "entities": [],
  "data": {
    "mute": false
  },
  "timestamp": 1594628899502,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

错误码

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

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

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