群组管理

大约 103 分钟

群组管理

环信即时通讯 IM 提供了 RESTful API 管理 App 中的群组。

单个 App 创建群组数量有限制，而且单个用户可加入群组的数量视版本而定，详见 使用限制。

前提条件

要调用环信即时通讯 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实际获取的数据详情。
uuidString用户在系统内的唯一标识。该标识由系统生成，开发者无需关心。
createdLong群组创建时间，Unix 时间戳，单位为毫秒。
timestampLongUnix 时间戳，单位为毫秒。
durationInt从发送请求到响应的时长，单位为毫秒。
propertiesString响应属性。

群组角色

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

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

认证方式

环信即时通讯 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
路径参数

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
groupnameString否群组名称，最大长度为 128 字符。
avatarString否群组头像的 URL，最大长度为 1024 字符。
descriptionString否群组描述，最大长度为 512 字符。
publicBool是是否是公开群。公开群可以被搜索到，用户可以申请加入公开群；私有群无法被搜索到，因此需要群主或群管理员添加，用户才可以加入。
- true：公开群；
- false：私有群。
scaleString否群组规模，取决于群成员总数 maxusers 参数。
- （默认）normal：普通群，即群成员总数不超过 3000。
- large：大型群，群成员总数超过 3000。

注意


- 创建大型群时，该参数必传；
- 大型群不支持离线推送。仅旗舰版支持创建大型群，如需该功能，请联系环信商务。

maxusersInt否群组最大成员数（包括群主）。对于普通群，该参数的默认值为 200，大型群为 1000。不同套餐支持的人数上限不同，详见 产品价格。
allowinvitesBool否是否允许普通群成员邀请用户加入群组：
- true：普通群成员可拉人入群;
- （默认）false：只有群主和群管理员才能拉人入群。

提示


创建群组时，该参数仅对私有群有效，对公开群无效。也就是说，创建公有群（public 设置为 true）时，即使将 allowinvites 设置为 true，该设置也会自动修改为 false。如果要允许公开群的普通成员拉人入群，你在创建群后可调用修改群组信息接口将 allowinvites 的设置修改为 true。

membersonlyBool否用户申请入群是否需要群主或者群管理员审批。
- true：需要；
- （默认）false：不需要，用户直接进群。
该参数仅对公开群生效，因为对于私有群，用户无法申请加入群组，只能通过群成员邀请加入群。
invite_need_confirmBool否邀请用户入群时是否需要被邀用户同意。
- （默认）true：是；
- false：否。
ownerString是群主的用户 ID。
membersArray否群成员的用户 ID 数组，不包含群主的用户 ID。该数组可包含的元素数量不超过 maxusers 的值。
customString否群组扩展信息，例如可以给群组添加业务相关的标记，不要超过 8 KB。

HTTP 响应

响应 body

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

字段类型描述
data.groupidString群组 ID。

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

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

示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "groupname": "testgroup",
   "avatar": "https://www.XXXX.com/XXX/image",
   "description": "test",
   "public": true,
   "maxusers": 300,
   "owner": "testuser",
   "members": [
     "user2"
   ]
 }' 'https://XXXX/XXXX/XXXX/chatgroups'
响应示例
{
  "action": "post",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups",
  "entities": [],
  "data": {
    "groupid": "6XXXX7"
  },
  "timestamp": 1542361730243,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400invalid_parameterXX must be providedXX 字段没有设置。请传入必传字段。
400invalid_parameteravatar length is too big头像字段长度达到上限修改头像字段在长度限制下。
400invalid_parametergroup must contain public field!创建群组必须设置 public 字段设置 public 字段。
400illegal_argumentgroup ID XX already exists!groupId 重复。使用新的群组 ID。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403exceed_limitappKey:XX#XX has create too many groups!appKey 的群组数量达到上限。删除不用的群组或联系商务调整上限。关于该上限，详见相关文档。
403exceed_limituser XX has joined too many groups!用户加入的群组数量达到上限。退出不用的群组或联系商务调整上限。关于该上限，详见相关文档。
403exceed_limitmembers size is greater than max user size !创建群时加入的人数超过最大限制。调整创建群的加群人数。关于该上限，详见相关文档。
403group_name_violationXX is violation, please change it.群组名称不合法。使用合法的群组名称。

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

封禁群组

封禁指定的群组。例如，群成员经常在群中发送违规消息，可以调用该 API 对该群进行封禁。群组被封禁后，群中任何成员均无法在群组以及该群组下的子区中发送和接收消息，也无法进行群组和子区管理操作。

群组封禁后，可调用解禁群组 API 对该群组解禁。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.disabledBool群组是否为禁用状态：
- 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/XXXX/disable'
响应示例
{
  "action": "post",
  "application": "XXXX",
  "applicationName": "XXXX",
  "data": {
    "disabled": true
  },
  "duration": 740,
  "entities": [],
  "organization": "XXXX",
  "properties": {},
  "timestamp": 1672974260359,
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/XXXX/disable"
}

错误码

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

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

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

解禁群组

解除对指定群组的封禁。群组解禁后，群成员可以在该群组以及该群组下的子区中发送和接收消息并进行群组和子区管理相关操作。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.disabledBool群组是否为禁用状态：
- 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/XXXX/enable'
响应示例
{
  "action": "post",
  "application": "XXXX",
  "applicationName": "XXXX",
  "data": {
    "disabled": false
  },
  "duration": 22,
  "entities": [],
  "organization": "XXXX",
  "properties": {},
  "timestamp": 1672974668171,
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/XXXX/enable"
}

错误码

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

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

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

修改群组信息

修改指定的群组信息，可修改 groupname、description、maxusers、membersonly、allowinvites、invite_need_confirm、public 和 custom 属性。如果传入其他字段，或传入的字段不存在，则不能修改的字段会抛出异常。

HTTP 请求

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

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
groupnameString否群组名称，最大长度为 128 字符。
avatarString否群组头像的 URL，最大长度为 1024 字符。
descriptionString否群组描述，最大长度为 512 字符。
maxusersInt否群组最大成员数（包括群主）。对于普通群，该参数的默认值为 200，大型群为 1000。不同套餐支持的人数上限不同，详见 产品价格。
membersonlyBool否加入群组是否需要群主或者群管理员审批：
- true：是；
- false：否。
allowinvitesBool否是否允许群成员邀请别人加入此群：
- true：允许群成员邀请人加入此群；
- false：只有群主或群管理员才可以邀请用户入群。
invite_need_confirmBool否受邀人加入群组前是否需接受入群邀请：
- true：需受邀人确认入群邀请；
- false：受邀人直接加入群组，无需确认入群邀请。
customString否群组扩展信息，例如可以给群组添加业务相关的标记，不要超过 1,024 字符。
publicBool否是否是公开群。
- true：公开群；
- false：私有群。

HTTP 响应

响应 body

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

字段类型描述
data.descriptionBool群组描述是否修改成功：
- true：修改成功；
- false：修改失败。
data.maxusersBool群组最大成员数是否修改成功：
- true：修改成功；
- false：修改失败。
data.groupnameBool群组名称是否修改成功：
- true：修改成功；
- false：修改失败。
data.avatarBool群组头像否修改成功：
- true：修改成功；
- false：修改失败。
data.membersonlyBool“加入群组是否需要群主或者群管理员审批”是否修改成功：
- true：修改成功；
- false：修改失败。
data.publicBool“是否是公开群”是否修改成功：
- true：修改成功；
- false：修改失败。
data.allowinvitesBool“是否允许群成员邀请其他用户入群”是否修改成功：
-true：修改成功；
- false：修改失败。
data.invite_need_confirmBool“受邀人加入群组前是否需接受入群邀请”是否修改成功：
- true：修改成功；
- false：修改失败。
data.customBool群组扩展信息是否修改成功：
-true：修改成功；
- false：修改失败。

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

示例

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

curl -X PUT -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/6XXXX7' -d '{
    "groupname": "test groupname",
    "avatar": "https://www.XXXX.com/XXX/image",
    "description": "updategroupinfo12311",
    "maxusers": 1500,
    "membersonly": true,
    "allowinvites": false,
    "invite_need_confirm": true,
    "custom":"abc",
    "public": true
}'
响应示例
{
  "action": "put",
  "application": "XXXXXX",
  "applicationName": "XXXX",
  "data": {
    "allowinvites": true,
    "invite_need_confirm": true,
    "membersonly": true,
    "public": true,
    "custom": true,
    "description": true,
    "maxusers": true,
    "groupname": true
  },
  "duration": 0,
  "entities": [],
  "organization": "XXXX",
  "properties": {},
  "timestamp": 1666062065529,
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_name_violationXX is violation, please change it.群组名称不合法。使用合法的群组名称。
403group_announce_violationgroup announcement is violation, please change it.群公告不合法。使用合法的群公告。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

获取 App 中的群组

分页获取应用下的群组的信息。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups?limit={N}&cursor={cursor}
路径参数

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

查询参数
参数类型是否必需描述
limitInt否每次期望返回的群组数量。取值范围为 [1,1000]，默认值为 10。若传入的值超过 1000，每页仍返回 1000 个群组。
cursorString否数据查询的起始位置。首次调用该接口，不传 cursor，服务器按群组创建时间倒序返回 limit 指定的群组数量。后续接口调用时，需要从上次调用的响应中获取 cursor 参数的值传入请求中的该参数。

提示

若请求中均未设置 limit 和 cursor 参数，环信服务器按群组创建时间倒序返回前 10 个群组。

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- ownerString群主的用户 ID。例如：{“owner”: “user1}。
- groupidString群组 ID。
- affiliationsint群组现有成员数。
- typeString“group” 群组类型。
- lastModifiedString最近一次修改的时间戳，单位为毫秒。
- groupnameString群组名称。
countInt实际获取的群组数量。
cursorString查询游标，指定下次查询的起始位置。

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

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

请求示例

第一页

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups?limit=2'

第二页

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups?limit=2&cursor=ZGNXXXX6Mg'
响应示例
{
  "action": "get",
  "params": {
    "limit": ["2"]
  },
  "uri": "https://XXXX/XXXX/XXXX/chatgroups",
  "entities": [],
  "data": [
    {
      "owner": "XXXX#testapp_user1",
      "groupid": "10XXXX60",
      "affiliations": 2,
      "type": "group",
      "lastModified": "1441021038124",
      "groupname": "testgroup1"
    },
    {
      "owner": "XXXX#testapp_user2",
      "groupid": "10XXXX76",
      "affiliations": 1,
      "type": "group",
      "lastModified": "1441074471486",
      "groupname": "testgroup2"
    }
  ],
  "timestamp": 1441094193812,
  "duration": 14,
  "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z",
  "count": 2
}

错误码

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

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

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

获取单个用户加入的所有群组

根据用户 ID 分页获取指定用户加入的所有群组。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/user/{username}?pagesize={}&pagenum={}
路径参数

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

查询参数
参数类型是否必需描述
pagesizeString否每页获取的群组数量。取值范围为 [1,20]，默认值为 5。若传入的值大于 20，每页仍返回 20 个群组。
pagenumString否当前页码。默认从第 0 页开始获取。
请求 header
参数类型是否必需描述
AcceptString是内容类型，请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

参数类型描述
totalInt用户加入的群组总数。
entitiesJSON Array用户加入的群组列表。
- groupId String群组 ID。
- nameString群组名称。
- avatarString群组头像的 URL。
- ownerString群主的用户 ID。
- descriptionString群组描述。
- disabledBool群组是否被禁用：
- true：禁用。禁用后不能对群组进行任何修改。
- false：未禁用。
- publicBool是否是公开群：
- true：公开群。公开群可以被搜索到，用户可以申请加入公开群。
- false：私有群。私有群无法被搜索到，需要群主或群管理员邀请，用户才可以加入。
- allowinvitesBool是否允许普通群成员邀请用户加入群组：
- true：普通群成员可拉人入群;
- false：只有群主或者管理员才可以拉人入群。
- membersonlyBool用户申请入群是否需要群主或者群管理员审批。
- true：需要；
- false：不需要，用户直接进群。
- maxusersInt群组最大成员数（包括群主）。
- created Long群组创建时间戳。

其他参数及说明详见 公共参数。

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

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'http://XXXX/XXXX/XXXX/chatgroups/user/XXXX' \
-H 'Authorization: Bearer  <YourAppToken>'
响应示例
{
  "action": "get",
  "applicationName": "XXXX",
  "duration": 0,
  "entities": [
    {
      "name": "群组名称",
      "avatar": "https://www.XXXX.com/XXX/image",
      "owner": "群组管理员",
      "id": "2XXXX1",
      "groupId": "2XXXX1",
      "description": "群组描述",
      "disabled": false,
      "public": false,
      "allowinvites": false,
      "membersonly": true,
      "maxusers": 2000,
      "created": 1692687427254
    }
  ],
  "organization": "XXXX",
  "timestamp": 1692687427254,
  "total": 10,
  "uri": "http://XXXX/XXXX/XXXX/chatgroups/user/XXXX"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。

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

查看指定用户是否已加入群组

查看单个用户是否已加入了指定的群组。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/user/{username}/is_joined
路径参数

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

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

HTTP 响应

响应 body

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

字段类型描述
dataBoolean该用户是否已加入群组：
- true：用户已加入该群组；
- false：用户未加入该群组。

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

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/XXXX/user/XXXX/is_joined'
响应示例
{
    "action": "get",
    "application": "8bXXXX02",
    "data": false,
    "duration": 0,
    "organization": "XXXX",
    "timestamp": 1691547476492
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。

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

获取群组详情

可以获取一个或多个群组的详情，最多可获取 100 个群组的详情。当获取多个群组的详情时，返回所有存在的群组的详情；对于不存在的群组，返回 “group id doesn’t exist”。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}
路径参数
参数类型是否必需描述
group_idString是要获取详情的群组 ID。最多可传 100 个群组 ID，群组 ID 之间用英文逗号（","）分隔。

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

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

HTTP 响应

响应 body

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

字段类型描述
countInt获取详情的群组数量。
dataJSON Array响应数据。
- idString群组 ID，群组唯一标识符。
- nameString群组名称。
- avatarString群组头像的 URL。
- descriptionString群组描述。
- membersonlyBool加入群组是否需要群主或者群管理员审批。
- true：是；
- false：否。
- allowinvitesBool是否允许群成员邀请其他用户加入此群。
- true：允许群成员邀请其他用户加入此群；
- false：只有群主可以邀请其他用户入群。
注：该参数仅对私有群有效，因为公开群不允许群成员邀请其他用户入群。
- maxusersInt群组最大成员数，创建群组的时候设置，可修改。
- affiliationsArray群组成员列表及其对应角色：
- owner：群主；
- member：群组管理员和普通成员。
- ownerString群主的用户 ID。例如：{“owner”: “user1”}。
- createdLong创建该群组的 Unix 时间戳。
- affiliations_countint群组现有成员总数。
- disabledBool群组是否为禁用状态：
- true：群组被禁用；
- false：群组为启用状态。
- muteBool是否处于全员禁言状态。
- true：是；
- （默认）false：否。
- publicBool是否是公开群：
- true：公开群；
- false：私有群。
- customString群组扩展信息，例如，可以给群组添加业务相关的标记，不要超过 1,024 字符。

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

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85'
响应示例
{
    "action": "get",
    "application": "09ebbf8b-XXXX-XXXX-bd4b-d47c3b38e434",
    "applicationName": "XXXX",
    "count": 1,
    "data": [
        {
            "id": "XXXX",
            "name": "XXXX",
            "avatar": "https://www.XXXX.com",
            "description": "XXXX",
            "membersonly": true,
            "allowinvites": false,
            "maxusers": 2000,
            "owner": "XXXX",
            "created": 1682588716646,
            "custom": "",
            "mute": false,
            "affiliations_count": 2,
            "disabled": false,
            "affiliations": [
                {
                    "member": "XXXX"
                },
                {
                    "owner": "XXXX"
                }
            ],
            "public": false
        }
    ],
    "duration": 35,
    "entities": [],
    "organization": "XXXX",
    "properties": {},
    "timestamp": 1682588814419,
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/XXXX"
}

错误码

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

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

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

解散群组

解散指定的群组。解散群组时会同时删除群组下所有的子区（Thread）。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.successBool群组删除结果:
- true：删除成功；
- false：删除失败。
data.groupidString删除的群组的 ID。

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

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

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://a1.Ago ra.com/XXXX/testapp/chatgroups/6XXXX7'
响应示例
{
  "action": "delete",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7",
  "entities": [],
  "data": {
    "success": true,
    "groupid": "6XXXX7"
  },
  "timestamp": 1542363546590,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

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

管理群组公告和共享文件

获取群组公告

获取指定群组 ID 的群组公告。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.announcementString群公告内容。

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

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

示例

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

curl -X GET -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/announcement'
响应示例
{
  "action": "get",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/announcement",
  "entities": [],
  "data": {
    "announcement": "群组公告..."
  },
  "timestamp": 1542363546590,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

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

修改群组公告

修改指定群组 ID 的群组公告。群组公告不能超过 512 个字符。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.idString群组 ID。
data.resultBool修改结果：
- true：修改成功；
- false：修改失败。

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

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

示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{"announcement" : "群组公告…"}' 'https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/announcement'
响应示例
{
  "action": "post",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/announcement",
  "entities": [],
  "data": {
    "id": "6XXXX7",
    "result": true
  },
  "timestamp": 1542363546590,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentannouncement is null没有传递公告内容。需传递公告内容。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
403FORBIDDENannounce info length exceeds limit!设置公告长度超限制。设置较短的公告

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

获取群组共享文件

可以分页获取指定群组 ID 的群组共享文件。获取文件后，你可以根据响应中返回的文件 ID（file_id）调用 下载群组共享文件 接口下载文件，或调用 删除群组共享文件 接口删除文件。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/share_files?pagenum={N}&pagesize={N}
路径参数

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

查询参数
参数类型是否必需描述
pagesizeString否每页期望返回的共享文件数。取值范围为 [1,1000]，默认为 1000。若传入的值超过 1000，返回 1000 个共享文件。
pagenumInt否当前页码。默认从第 1 页开始获取。
请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- file_idString群组共享文件的 ID，若要下载或删除该文件需要使用该参数。
- file_nameString群组共享文件名称。
- file_ownerString上传群组共享文件的用户 ID。
- file_sizeLong群组共享文件大小，单位为字节。
- createdLong上传群组共享文件的时间。

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

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

示例

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

curl -X GET -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files?pagenum=1&pagesize=10'
响应示例
{
  "action": "get",
  "application": "8bXXXX02",
  "params": {
    "pagesize": ["10"],
    "pagenum": ["1"]
  },
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files",
  "entities": [],
  "data": [
    {
      "file_id": "dbd88d20-e1d4-11ea-95fc-638fc2d59a8d",
      "file_name": "159781149272586.jpg",
      "file_owner": "u1",
      "file_size": 326127,
      "created": 1597811492594
    },
    {
      "file_id": "b30XXXX4f",
      "file_name": "159781141836993.jpg",
      "file_owner": "u1",
      "file_size": 326127,
      "created": 1597811424158
    }
  ],
  "timestamp": 1542363546590,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

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

上传群组共享文件

上传指定群组 ID 的群组共享文件。注意上传的文件大小不能超过 10 MB。

分页获取指定群组 ID 的群组共享文件，然后可以根据响应中返回的文件 ID（file_id）调用 下载群组共享文件 接口下载该文件，或调用 删除群组共享文件 接口删除该文件。

HTTP 请求

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

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

请求 header
参数类型是否必需描述
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
Content-TypeString是内容类型。请填 multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW。
fileString是待上传文件的本地路径。

HTTP 响应

响应 body

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

字段类型描述
data.file_urlString群组共享文件的 URL，在环信即时通讯 IM 服务器上保存的地址。
data.group_idString群组 ID。
data.file_nameString群组共享文件名称。
data.createdLong上传群组共享文件的时间。
data.file_idString群组共享文件 ID，可以用于下载和删除共享文件。
data.file_sizeLong群组共享文件大小，单位为字节。

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

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

示例

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

curl -X POST 'https://XXXX/XXXX/XXXX/chatgroups/66021836783617/share_files' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -F file=@/Users/test/image/IMG_3.JPG
响应示例
{
  "action": "post",
  "application": "7fXXXXef",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files",
  "entities": [],
  "data": {
    "file_url": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files/c6XXXXc0",
    "group_id": "6XXXX7",
    "file_name": "img_3.jpg",
    "created": 1599050554954,
    "file_id": "c6XXXXc0",
    "file_size": 13512
  },
  "timestamp": 1599050554978,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404RestGroupFeignExceptiongrpID XX does not exist!群组不存在。使用合法的群 ID。
400IllegalArgumentExceptionfile must be provided.群共享文件未提供上传群共享文件

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

下载群组共享文件

根据指定的群组 ID 与文件 ID（file_id）下载群组共享文件，文件 ID 可从 获取群组共享文件 接口的响应中获取。

HTTP 请求

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

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

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

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应体中为上传的文件的内容，例如，上传的文件内容为“Hello world”，响应中返回“Hello world”。

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

示例

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

curl -X GET -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files/b30XXXX4f'
响应示例

返回上传的文件的内容。例如，上传的文件内容为“Hello world”，响应中返回“Hello world”。

错误码

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

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

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

删除群组共享文件

根据指定的群组 ID 与 文件 ID（file_id）删除群组共享文件，文件 ID 可从 获取群组共享文件 接口的响应中获取。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/share_files/{file_id}
路径参数
参数类型是否必需描述
file_idString是文件 ID。

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

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

HTTP 响应

响应 body

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

字段类型描述
data.group_idString群组 ID。
data.file_idString群组共享文件 ID。在下载共享文件时需提供该参数。
data.resultBool删除群组共享文件的结果：
- 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/6XXXX7/share_files/b30XXXX4f'
响应示例
{
  "action": "delete",
  "application": "8bXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatgroups/6XXXX7/share_files/b30XXXX4f",
  "entities": [],
  "data": {
    "group_id": "6XXXX7",
    "file_id": "b30XXXX4f",
    "result": true
  },
  "timestamp": 1599049350114,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

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

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

管理群组成员

环信即时通讯 IM 提供多个接口实现对群组成员的管理，包括添加和移除群组成员、转让群组所有权以及群组黑名单、白名单和禁言列表相关操作。

分页获取群成员列表

可以分页获取群组成员列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/users?pagenum={N}&pagesize={N}
路径参数

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

查询参数
参数类型是否必需描述
pagenumInt否当前页码。默认从第 1 页开始获取。
pagesizeInt否每页期望返回的群组成员数量。取值范围为 [1,1000]。默认为 1000。若传入的值大于 1000，则获取 1000 个群组成员。
请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

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

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

如果返回的 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404service_resource_not_founddo not find this group:XX群组不存在。使用合法的群 ID。

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

添加单个群组成员

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

HTTP 请求

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

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 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。
AuthorizationString是App 管理员的鉴权 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。
AuthorizationString是App 管理员的鉴权 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。
AuthorizationString是App 管理员的鉴权 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 以内。

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

设置群成员自定义属性

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

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

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/user/{username}
路径参数

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
metaDataJSON是要设置的群成员自定义属性，为 key-value 键值对。对于单个键值对：
- key 表示属性名称，不能超过 16 字节。
- value 表示属性值，不能超过 512 个字节。若 value 设置为空字符串即删除该自定义属性。

注意

单个群成员的自定义属性总长度不能超过 4 KB。

HTTP 响应

响应 body

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

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

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

如果返回的 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 状态码错误类型错误提示可能原因处理建议
400metadata_errorexceeds chatgroup user metadata single key limit添加的群成员属性的 key 过长。调整群成员属性 key 的长度。属性 key 不能超过 16 字节。
400metadata_errorexceeds chatgroup user metadata single value limit添加的群成员属性的 value 过长。调整群成员属性 value 的长度。value 不能超过 512 个字节。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。

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

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

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/user/{username}
路径参数

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

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON获取的群成员自定义属性。

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

如果返回的 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404MetadataExceptionuser not in group用户不在群组内。使用正确的群组成员的用户 ID。

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

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

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/metadata/chatgroup/{group_id}/get
路径参数

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
targetsJSON Array是要获取自定义属性的群成员的用户 ID。一次最多可传 10 个用户 ID。
propertiesJSON Array是要获取自定义属性的 key 的数组。若该参数设置为空数组或不传，则获取这些群成员的所有自定义属性。

HTTP 响应

响应 body

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

字段类型描述
dataJSON获取的群成员的自定义属性。如下响应示例中的 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 状态码错误类型错误提示可能原因处理建议
400metadata_errorquery param reaches limit.批量查询数量达到限制。减少要查询的用户 ID。每次最多可获取 10 个群成员的自定义属性。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。

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

获取群管理员列表

获取群组管理员列表。

HTTP 请求

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

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 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
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 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}
路径参数

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 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。

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

转让群组

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

HTTP 请求

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

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

请求 header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 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。

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

管理黑名单

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

查询群组黑名单

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

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
countInt群组黑名单中的用户数量。
dataArray群组黑名单上的用户 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

将单个用户添加至群组黑名单。群主无法被加入群组的黑名单。

用户进入群组黑名单后会收到加入黑名单的回调。之后，该用户无法查看该群组的信息，也收不到该群组的消息。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.resultBool添加结果：
- true：添加成功；
- false：添加失败。
data.actionString执行操作。在该响应中，该字段的值为 add_blocks，表示将成员添加至群组黑名单。
data.userString添加的用户 ID。
data.groupidString群组 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要添加黑名单的用户 ID 不在群组中。使用群组成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

将多个用户添加至群组黑名单，一次最多可以添加 60 个用户。群主无法被加入群组的黑名单。

用户进入群组黑名单后会收到加入黑名单的回调。黑名单上的用户无法查看该群组的信息，也收不到该群组的消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/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，表示请求成功，响应包体中包含以下字段：

字段类型描述
dataJSON Array响应数据。
- resultBool添加结果：
- true：添加成功；
- false：添加失败。
- actionString执行的操作。在该响应中，该字段的值为 add_blocks，表示将群成员加入群组黑名单。
- reasonString添加失败的原因。
- userString添加的用户 ID。
- groupidString群组 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 状态码错误类型错误提示可能原因处理建议
400invalid_parameteruserNames is more than max limit : 60批量添加的用户数超过了上限 60。调整要移除的数量在限制以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要添加黑名单的用户 ID 不在群组中。使用群组成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

将指定用户移出群组黑名单。对于群组黑名单中的用户，如果需要将其再次加入群组，需要先将其从群组黑名单中移除。

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
resultBool移除结果：
- true：移除成功；
- false：移除失败。
actionString执行的操作。在该响应中，该字段的值为 remove_blocks，表示将群成员移出群组黑名单。
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/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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要移除黑名单的用户 ID 不在群组中。传入群组黑名单中的群成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

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

对于群组黑名单中的用户，如果要将其再次加入群组，需先将其从群组黑名单中移除。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{usernames}
路径参数
参数类型是否必需描述
usernamesString是要移除群组黑名单的用户 ID，一次最多可传 60 个，用户 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_blocks，表示将用户从群组黑名单批量移除。
- 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/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 状态码错误类型错误提示可能原因处理建议
400invalid_parameterremoveBlacklist: list size more than max limit : 60批量删除超过上限 60。调整要移除的数量在限制以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要移除黑名单的用户 ID 不在群组中。传入群组黑名单中的群成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

管理白名单

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

查询群组白名单

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

HTTP 请求

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

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

请求 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 -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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

将指定的单个用户添加至群组白名单。用户添加至群组白名单后，当群组全员被禁言时，仍可以在群组中发送消息。

HTTP 请求

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

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

请求 header
参数类型是否必需描述
AcceptString是内容类型。请填 application/json。
AuthorizationString是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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要添加白名单的用户 ID 不在群组中。传入群组成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

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

添加多个用户至群组白名单。你一次最多可添加 60 个用户。

用户添加至白名单后在群组全员禁言时仍可以在群组中发送消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/white/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，表示请求成功，响应包体中包含以下字段：

字段类型描述
dataJSON Array响应数据。
- resultBool添加结果：
- true：添加成功；
- false：添加失败。
- actionString执行的操作。在该响应中，该字段的值为 add_user_whitelist，表示将成员加入群白名单。
- userString添加的用户 ID。
- groupidString群组 ID。
- reasonString添加失败的原因。

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

如果返回的 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 状态码错误类型错误提示可能原因处理建议
400invalid_parameterusernames size is more than max limit : 60批量添加白名单的群成员超过了上限 60。调整要添加的数量在限制（60）以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要添加白名单的用户 ID 不在群组中。传入群组成员的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

从群组白名单移除用户

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/white/users/{username}
路径参数
参数类型是否必需描述
usernameString是要从群组白名单中移除的用户 ID，最多可传 60 个，用户 ID 之间以英文逗号（","）分隔。

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

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- resultBool移除结果：
- true：移除成功；
- false：移除失败。
- actionString执行的操作。在该响应中，该字段的值为 remove_user_whitelist，表示将成员移出群组白名单。
- userString移除群组白名单的用户 ID，多个用户 ID 以英文逗号（","）分隔。
- groupidString群组 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 状态码错误类型错误提示可能原因处理建议
400invalid_parameterremoveWhitelist size is more than max limit : 60批量移除白名单的群成员数量超过了上限 60。调整要移除的数量在限制（60）以下。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要移除白名单的用户 ID 不在群组中。传入在群组白名单中的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

管理禁言

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

获取禁言列表

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

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- expireLong禁言到期的时间，单位为毫秒。
- userString被禁言用户的 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群组 ID。

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

禁言指定群成员

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

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

HTTP 请求

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

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
mute_durationLong是禁言时长，单位为毫秒。
usernamesArray是要添加到禁言列表的用户 ID 列表，每次最多可添加 60 个。

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- resultBool操作结果：
- true：添加成功；
- false：添加失败。
- expireLong禁言到期的时间。该时间为 Unix 时间戳，单位为毫秒。
- userString被禁言用户的 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403forbidden_opusers [XX] are not members of this group!要禁言的用户 ID 不在群组中。传入群组中的用户 ID。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
400invalid_parameteruserNames size is more than max limit : 60批量禁言指定群成员数量超过60控制禁言指定群成员数量在 60 以内。

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

禁言全体群成员

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

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.muteBool操作结果：
- 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

解除成员禁言

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

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/mute/{member1}(,{member2},…)
路径参数
参数类型是否必需描述
memberString是要解除禁言的成员的用户 ID，每次最多可传 60 个，多个用户 ID 之间以英文逗号（","）分隔，例如 {member1},{member2}。

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

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array响应数据。
- resultBool操作结果：
- true：解除成功；
- false：解除失败。
- userArray被移出禁言列表的用户 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。
400invalid_parameterremoveMute member size more than max limit : 60批量移除禁言列表的用户数超过上限 60。控制解除成员禁言数量在 60 以内。

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

解除全员禁言

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

HTTP 请求

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

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

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

HTTP 响应

响应 body

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

字段类型描述
data.muteBool是否处于全员禁言状态。
- 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 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404resource_not_foundgrpID XX does not exist!群组不存在。使用合法的群 ID。

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

管理子区

环信即时通讯 IM 提供多个接口实现子区管理，包括子区的创建、获取、修改和删除等。

单个 app 下的子区总数默认为 10 万，如需调整请联系商务。

获取 app 中的子区

分页获取应用下的子区列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/thread?limit={limit}&cursor={cursor}&sort={sort}
路径参数

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

查询参数
参数类型是否必需描述
limitInt否每次期望返回的子区数量，取值范围为 [1,50]，默认值为 50。
cursorString否数据查询的起始位置。
sortString否获取的子区的排序顺序：
- asc：按子区创建时间的正序；
- （默认）desc：按子区创建时间的倒序。
请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array响应数据。
- idString子区 ID。
properties.cursorString查询游标，指定下次查询的起始位置。

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

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

示例

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

curl -X GET https://XXXX/XXXX/XXXX/thread -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "applicationName": "testapp",
  "duration": 7,
  "entities": [
    {
      "id": "1XXXX8"
    }
  ],
  "organization": "XXXX",
  "properties": {
    "cursor": "ZGXXXXTE"
  },
  "timestamp": 1650869750247,
  "uri": "https://XXXX/XXXX/XXXX/thread"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorquery param reaches limit.分页参数 limit 的值过大。检查查询参数 limit 是否在取值范围（[1,50]）内。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。

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

获取单个用户加入的所有子区（分页获取）

根据用户 ID 获取该用户加入的所有子区。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/threads/user/{username}?limit={limit}&cursor={cursor}&sort={sort}
路径参数

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

查询参数
参数类型是否必需描述
limitInt否每次期望返回的子区数量，取值范围为 [1,50]，默认值为 50。
cursorString否数据查询的起始位置。
sortString否获取的子区的排序顺序：
- asc：按用户加入子区的时间的正序；
- （默认）desc：按用户加入子区的时间的倒序。
请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array响应数据。
- nameString子区名称。
- ownerString子区创建者的用户 ID。
- entities.idString子区 ID。
- entities.msgIdString子区的父消息 ID。
- entities.groupIdString子区所属群组 ID。
- entities.createdLong子区创建时间，Unix 时间戳。
properties.cursorString查询游标，指定服务器下次查询的起始位置。

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

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

示例

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

curl -X GET https://XXXX/XXXX/XXXX/threads/user/test4 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "applicationName": "testapp",
  "duration": 4,
  "entities": [
    {
      "name": "1",
      "owner": "test4",
      "id": "17XXXX69",
      "msgId": "1920",
      "groupId": "17XXXX61",
      "created": 1650856033420
    }
  ],
  "organization": "XXXX",
  "properties": {
    "cursor": "ZGXXXXzg"
  },
  "timestamp": 1650869972109,
  "uri": "https://XXXX/XXXX/XXXX/threads/user/test4"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorquery param reaches limit.分页参数 limit 的值过大。检查查询参数 limit 是否在取值范围（[1,50]）内。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。

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

获取单个用户在指定群组中加入的所有子区 (分页获取)

根据用户 ID 获取该用户在指定群组中加入的所有子区。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/threads/chatgroups/{group_id}/user/{username}?limit={limit}&cursor={cursor}&sort={sort}
路径参数

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

查询参数
参数类型是否必需描述
limitInt否每次期望返回的子区数量，取值范围为 [1,50]，默认值为 50。该参数仅在分页获取时为必需。
cursorString否数据查询的起始位置。该参数仅在分页获取时为必需。
sortString否获取的子区的排序顺序：
- asc：按用户加入子区的时间的正序；
- （默认）desc：按用户加入子区的时间的倒序。
请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

若为最后一页数据，响应中仍会返回 cursor，而且获取的子区数量小于请求中的 limit 的值；若响应中不再返回子区数据，表示你已经获取该群组下的所有子区数据。

字段类型描述
entitiesJSON Array响应数据。
- nameString子区名称。
- ownerString子区的创建者。
- idString子区 ID。
- msgIdString子区的父消息 ID。
- groupIdString子区所属群组 ID。
- createdLong子区创建时间，Unix 时间戳，单位为毫秒。
- cursorString查询游标，指定下次查询的起始位置。

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

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

示例

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

curl -X GET https://XXXX/XXXX/XXXX/threads/chatgroups/XXXX/user/XXXX -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "applicationName": "testapp",
  "duration": 4,
  "entities": [
    {
      "name": "1",
      "owner": "test4",
      "id": "17XXXX69",
      "msgId": "1920",
      "groupId": "17XXXX61",
      "created": 1650856033420
    }
  ],
  "organization": "XXXX",
  "properties": {
    "cursor": "ZGXXXXNzg"
  },
  "timestamp": 1650869972109,
  "uri": "https://XXXX/XXXX/XXXX/threads/user/test4"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorquery param reaches limit.分页参数 limit 的值过大。检查查询参数 limit 是否在取值范围（[1,50]）内。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。

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

创建子区

创建子区。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/thread
路径参数

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
group_idString是子区所在的群组 ID。
nameString是子区名称，不能超过 64 个字符。
msg_idString是子区的父消息 ID。
ownerString是子区的所有者，即创建子区的群成员。

HTTP 响应

响应 body

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

字段类型描述
data.thread_idString创建的子区 ID。

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

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

示例

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

curl -X POST https://XXXX/XXXX/XXXX/thread -H 'Authorization: Bearer <YourAppToken>' -H 'Content-Type:application/json' -d '{
    "group_id": 179800091197441,
    "name": "1",
    "owner": "test4",
    "msg_id": 1234
}'
响应示例
{
    "action": "post",
    "applicationName": "testapp",
    "duration": 4,
    "data": {
        "thread_id": "1XXXX7"
    },
    "organization": "XXXX",
    "timestamp": 1650869972109,
    "uri": "https://XXXX/XXXX/XXXX/thread"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorthread must on group message to create.消息 ID 不是群消息。输入正确的群消息 ID。
400group_errorthread name limit reached.子区名称过长。请提供长度范围内的子区名称。子区名称长度不能超过 64 个字符。
400param_illegalFailed to read HTTP messagebody 参数不合法。检查 body 参数是否合法。
400group_errormsg not belong to app.消息不属于 app。输入合法的消息 ID。
400group_errormsg not belong to group .消息不属于群。输入合法的消息 ID。
400group_errorthread not nested.不允许在子区的消息上创建子区。输入合法的消息 ID。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread number has reached limit.appKey 创建子区达到上限。删除废弃的子区或者联系商务调整上限。单个 app 下的子区总数默认为 10 万。
403group_erroruser join thread reach limit.用户加入的子区达到上限。退出不用的子区或者联系商务调整上限。单个用户默认最多可以加入 100,000 个子区。
403group_errormsg already create thread.not allow to create.消息上已经创建子区。传入其他消息 ID 或者查询该子区后加入。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。
404group_erroruser not in group.子区所有者不在群里面。输入已加入群的用户 ID。
404group_errormsg not exist.消息不存在。输入存在的消息 ID。
404group_errorgroup not found.群组不存在。检查创建子区的群组是否存在。

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

修改子区

修改指定子区。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/thread/{thread_id}
路径参数
参数类型是否必需描述
thread_idString是子区 ID。

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
nameString是要修改的子区的名称。修改后的子区名称不能超过 64 个字符。

HTTP 响应

响应 body

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

字段类型描述
data.nameString修改后的名称。

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

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

示例

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

curl -X PUT https://XXXX/XXXX/XXXX/thread/1XXXX7 -H 'Authorization: Bearer <YourAppToken>' -d '{"name": "test4"}'
响应示例
{
    "action": "put",
    "applicationName": "testapp",
    "duration": 4,
    "data": {
        "name": "test4"
    },
    "organization": "XXXX",
    "timestamp": 1650869972109,
    "uri": "https://XXXX/XXXX/XXXX/thread"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorthread name limit reached.子区名称过长。请提供长度范围内的子区名称。子区名称长度不能超过 64 个字符。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。
404group_errorthread not found.子区不存在。输入正确的子区 ID。

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

删除子区

删除指定子区。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/thread/{thread_id}
路径参数
参数类型是否必需描述
thread_idString是子区 ID。

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

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

HTTP 响应

响应 body

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

字段类型描述
data.statusString删除结果，ok 表示成功删除。

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

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

示例

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

curl -X DELETE https://XXXX/XXXX/XXXX/thread/1XXXX7 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "applicationName": "testapp",
  "duration": 4,
  "data": {
    "status": "ok"
  },
  "organization": "XXXX",
  "timestamp": 1650869972109,
  "uri": "https://XXXX/XXXX/XXXX/thread"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。
404group_errorthread not found.子区不存在。输入正确的子区 ID。

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

管理子区成员

环信即时通讯 IM 提供多个接口实现子区成员管理，包括对加入和踢出子区等管理功能。

获取子区成员列表(分页)

获取指定子区的成员列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/thread/{thread_id}/users?limit={N}&cursor={cursor}
路径参数

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

查询参数
参数类型是否必需描述
limitInt否每次期望返回的子区成员数量，取值范围为 [1,50]，默认值为 50。该参数仅在分页获取时为必需。
cursorString否数据查询的起始位置。该参数仅在分页获取时为必需。
请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
affiliationsArray子区成员的用户 ID 列表。
properties.cursorString查询游标，指定下次查询的起始位置。

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

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

示例

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

curl -X GET https://XXXX/XXXX/XXXX/thread/1XXXX7/users -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "data": {
    "affiliations": ["test4"]
  },
  "duration": 4,
  "properties": {
    "cursor": "ZGNXXXXyMA"
  },
  "timestamp": 1650872048366,
  "uri": "https://XXXX/XXXX/XXXX/thread/1XXXX8/users"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorquery param reaches limit.分页参数 limit 的值过大。检查查询参数 limit 是否在取值范围内。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。
404group_errorthread not found.子区不存在。输入正确的子区 ID。

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

用户批量加入子区

用户批量加入指定的子区。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/thread/{thread_id}/users
路径参数
参数类型是否必需描述
thread_idString是子区 ID。

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需备注
usernamesList是批量加入子区的用户 ID 列表。每次最多支持 10 个用户加入子区。

HTTP 响应

响应 body

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

字段类型描述
data.statusString添加结果，ok 表示成功添加。

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

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

示例

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

curl -X POST https://XXXX/XXXX/XXXX/thread/1XXXX7/users -d '{
"usernames": [
"test2",
"test3"
]
}' -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "post",
  "applicationName": "testapp",
  "data": {
    "status": "ok"
  },
  "duration": 1069,
  "organization": "XXXX",
  "timestamp": 1650872649160,
  "uri": "https://XXXX/XXXX/XXXX/thread/1XXXX8/joined_thread"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorrequest body reaches limit.请求 body 中的 usernames 参数的值已超过上限。请检查请求 body 中的 usernames 参数的值是否超过了 10。每次最多支持 10 个用户加入子区。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。
403group_erroruser join thread reach limit.用户加入的子区达到上限。退出不用的子区或者联系商务调整上限。
404group_errorthread not found.子区不存在输入正确的子区 ID。

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

批量踢出子区成员

批量踢出子区成员。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/thread/{thread_id}/users
路径参数
参数类型是否必需描述
thread_idString是子区 ID。

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

请求 header
参数类型是否必需描述
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需备注
usernamesList是批量踢出子区的用户 ID 列表。每次最多可踢出 10 个子区成员。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array响应数据。
- resultBool操作结果。
- true：成功；
- false：失败。
- userString被踢出子区的用户 ID。

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

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

示例

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

curl -X DELETE https://XXXX/XXXX/XXXX/thread/1XXXX7/users -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "applicationName": "testy",
  "duration": 12412,
  "entities": [
    {
      "result": false,
      "user": "test2"
    },
    {
      "result": false,
      "user": "test6"
    }
  ],
  "organization": "XXXX",
  "timestamp": 1650874050419,
  "uri": "https://XXXX/XXXX/XXXX/thread/1XXXX8/users"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
400group_errorrequest body reaches limit.请求 body 中的 usernames 参数的值已超过上限。请检查请求 body 中的 usernames 参数的值是否超过了 10。每次最多可踢出 10 个子区成员。
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
404group_errorthread not found.子区不存在输入正确的子区 ID。
403group_errorthread not open.子区功能未开通。请在环信即时通讯控制台开通子区服务。

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

环信 IM 文档 Version: 1.0.0 ©️环信