身份组是圈组功能的权限管理系统。您可通过身份组，实现对服务器成员和频道成员的精细化权限控制。

服务器身份组负责在服务器维度对用户进行权限控制。服务器身份组包括服务器下的@everyone 身份组和自定义身份组。创建服务器时，@everyone 身份组默认自动创建。而服务器自定义身份组则需要用户手动创建。此外，拥有相应权限（具体见下文）的用户还可调整服务器身份组的优先级。

身份组相关的功能概述，请参见 身份组概述。

本文包含如下 API 的说明：

• 创建服务器身份组
• 修改服务器身份组
• 删除服务器身份组
• 批量更新服务器身份组优先级
• 分页查询服务器身份组

使用限制

单个服务器内可创建的服务器身份组数量上限，默认为 20 个。

可在云信控制台配置单个服务器内的身份组数量上限。（在云信控制台选择应用，进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 单server可创建的身份组即可配置。

创建服务器身份组

调用如下 API 可创建服务器自定义身份组。自定义身份组创建后，其权限项的状态（开启或关闭）默认继承已有的身份组的权限之和，具体计算规则为：取有（即“开启”）不取无（即“关闭”）、多组取并集。如需调整权限项的状态，需要拥有管理角色权限的用户手动修改（具体见下文的修改服务器身份组）。

除服务器创建者以外的用户调用本 API 需要拥有管理角色权限。

URL

httpPOST https://api.netease.im/nimserver/qchat/createServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参考 API 调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
accid	String	是	操作者的 IM 账号
serverId	Long	是	服务器 ID
type	int	是	类型：2为自定义身份组，目前只能设置为2
name	String	是	身份组名称
icon	String	否	身份组图标url
ext	String	否	自定义扩展，最大长度1024
priority	String	否	优先级数值，正数。数值越小，优先级越大，最小为1，@everyone 身份组为 0，但不参与比较 如果新创建的身份组的优先级数值跟已有身份组优先级数值重复，将报错（状态码：403）。更多身份组优先级说明，参见下文的批量更新服务器身份组优先级
bid	String	否	安全通的自定义反垃圾（即内容审核）业务的 ID，可转换 JSON 格式，如： {"textbid":"","picbid":""} 自定义反垃圾业务主要用来针对圈组的资料信息进行除了默认反垃圾业务以外的内容审核。开通安全通后，云信控制台会自动生成默认反垃圾业务。您的应用不需要配置业务 ID 就能默认采用安全通的默认反垃圾业务，如果需要自定义反垃圾业务，请先通过云信官网首页提供的微信、在线聊天和电话等方式跟商务经理发出申请，获取对应的业务 ID。

示例

cURL请求示例

curlcurl -X POST -H "AppKey: go9dn**03mgq3" -H "Nonce: 4tg**23t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&type=2&name="新身份组1"&icon="iconurl"&ext="ext"&priority=12' 'http://api.netease.im/nimserver/qchat/createServerIdentify.action'

返回示例

请求成功的返回示例如下：

http 响应:json

json"Content-Type": "application/json; charset=utf-8"
{
	"code": 200,
	"identify": {
		"ext": "ext",//扩展字段
		"membercount": 1,//身份组的成员数
		"createtime": 1,//创建时间
		"roleId": 1,//身份组的唯一标识
		"auths": "{\"1\":-1, \"2\":1}",//身份组的权限，key为权限的枚举值，value为1允许，-1拒绝，服务器身份组只有允许和拒绝
		"name": "name",//身份组名称
		"icon": "icon",//身份组图标url
		"priority": 1,//身份组的优先级，优先级数字越小优先级越高，1为最高，everyone为特殊身份组为0不参与其他身份组的比较
		"type": 1,//身份组的类型1：@everyone身份组，2：自定义身份组
		"updatetime": 1//更新时间
	}
}

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见 状态码。

修改服务器身份组

调用本 API 可修改自定义服务器身份组信息，包括身份组权限项的状态、身份组名称、身份组图标等

• 除服务器创建者以外的用户调用本 API 需要拥有管理角色权限。
• 仅自定义身份组（即 type 为 2 的身份组）支持调用该接口更新身份组信息。创建服务器时默认创建的 @everyone 身份组 （即 type 为 1 的身份组）不支持调用该接口更新其信息。@everyone 身份组仅支持修改其权限。如果调用该接口更新 @everyone 身份组的信息（身份组的名称，图标，自定义扩展，优先级）， 将报错（错误码 403）。

URL

httpPOST https://api.netease.im/nimserver/qchat/updateServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参考 API 调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
accid	String	是	操作者的 IM 账号
serverId	String	是	服务器 ID
roleId	String	是	服务器身份组 ID
name	String	否	身份组名称
icon	String	否	身份组图标url
ext	String	否	自定义扩展，最大长度1024
auths	String	否	用于修改权限的 JSON 字段, 其格式为 {resource1:type1,resource2:type2,resource3:type3}。 resource 表示权限项, 其取值代表的具体权限项如下： 1：管理服务器的权限，拥有该权限可修改服务器信息（包括基本属性、服务器名称、图标、成员数、邀请模式等） 2：管理频道的权限，拥有该权限可创建、修改或删除频道 3：管理角色的权限，拥有该权限可创建、修改或删除身份组 4：发送消息的权限 5：修改自己的服务器成员信息的权限 6：邀请他人加入服务器的权限 7：将他人踢出服务器的权限 8：修改他人的服务器成员信息的权限 9：撤回他人消息的权限 10：删除他人消息的权限 11：@ 他人的权限，拥有该权限可在发送消息时@他人 12：@ 所有人的权限，拥有该权限可在发送消息时@所有人 13：管理频道黑白名单的权限，拥有该权限可将服务器成员加入或移出频道黑白名单 14：封禁他人的权限，拥有该权限可封禁服务器成员，被封禁者将被直接踢出服务器且无法再度加入服务器 15：实时互动频道：建立自己连接的权限 16：实时互动频道：断开他人连接的权限 17：实时互动频道：开启自己麦克风的权限 18：实时互动频道：开启自己摄像头的权限 19：实时互动频道：开启/关闭他人麦克风的权限 20：实时互动频道：开启/关闭他人摄像头的权限 21：实时互动频道：开启/关闭全员麦克风的权限 22：实时互动频道：开启/关闭全员摄像头的权限 23：实时互动频道：打开自己屏幕共享的权限 24：实时互动频道：关闭他人屏幕共享的权限 25：处理“加入服务器申请”的权限 26：申请邀请历史查看权限，有这个权限才可以查询server级别的申请/邀请记录 27：@身份组的权限，拥有该权限可在发送消息时@指定几个身份组的所有成员 28：临时禁言权限，拥有该权限可在服务器/频道维度中临时禁言其他成员（包括临时禁言、解除禁言、查询禁言成员和禁言操作记录） type 表示操作类型，其取值代表的操作如下： -1：关闭权限（deny） 1：开启权限（allow） 注：单次最多可批量更新当前身份组的所有权限。
bid	String	否	安全通的自定义反垃圾（即内容审核）业务的 ID，可转换 JSON 格式，如： {"textbid":"","picbid":""} 自定义反垃圾业务主要用来针对圈组的资料信息进行除了默认反垃圾业务以外的内容审核。开通安全通后，云信控制台会自动生成默认反垃圾业务。您的应用不需要配置业务 ID 就能默认采用安全通的默认反垃圾业务，如果需要自定义反垃圾业务，请先通过云信官网首页提供的微信、在线聊天和电话等方式跟商务经理发出申请，获取对应的业务 ID。

返回参数

参数	说明
code	状态码
identify	修改后的身份组，具体字段信息见下表

identify 的字段	说明
ext	身份组的扩展字段
membercount	身份组的成员数量
createtime	身份组的创建时间
roleId	身份组 ID
auths	身份组的权限配置列表，示例："{"1":-1, "2":1}"，其中 key为权限项的枚举值，value 为该权限项的配置状态： 1-开启（身份组成员拥有该权限） -1：关闭（身份组成员没有该权限） 服务器身份组的配置状态只有开启或关闭，没有继承
name	身份组名称
icon	身份组的图标 URL
priority	身份组的优先级，优先级数字越小优先级越高，1 为最高。默认的 @everyone身份组 为特殊身份组，其优先级为 0。 当用户拥有管理身份组的权限后，可对等级低于自身最高优先级身份组的其他身份组进行操作（如修改权限配置），也可创建一个新的自定义身份组，并对其进行优先级排序
type	身份组类型，1：@everyone身份组，2：自定义身份组
updatetime	身份组的更新时间

示例

cURL请求示例

curlcurl -X POST -H "AppKey: go9dnk49**kglw0803mgq3" -H "Nonce: 4tggg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&roleId=2&name="新身份组1"&icon="iconurl"&ext="ext"&auths="{\"1\":1}"' 'http://imtest.netease.im/nimserver/qchat/updateServerIdentify.action'

返回示例

请求成功的返回示例如下：

json"Content-Type": "application/json; charset=utf-8"
{
	"code": 200,
	"identify": {
		"ext": "ext",
		"membercount": 1,
		"createtime": 1,
		"roleId": 1,
		"auths": "{\"1\":-1, \"2\":1}",
		"name": "name",
		"icon": "icon",
		"priority": 1,
		"type": 1,
		"updatetime": 1
	}
}

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见 状态码。

删除服务器身份组

如果需要删除某个服务器身份组，可通过本 API 进行删除。

• 服务器创建者以外用户调用该方法必须先拥有管理角色权限，且必须是相应服务器的成员。
• @everyone 身份组默认不可删除。
• 用户无法删除优先级高于自己已有身份组的最高优先级的身份组。

URL

httpPOST https://api.netease.im/nimserver/qchat/removeServerIdentify.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参考 API 调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
accid	String	是	操作者的 IM 账号
serverId	String	是	服务器 ID
roleId	int	是	身份组 ID

示例

curl请求示例

curlcurl -X POST -H "AppKey: go9dnk4**803mgq3" -H "Nonce: 4tg**323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&roleId=2' 'http://imtest.netease.im/nimserver/qchat/removeServerIdentify.action'

返回示例

http 响应:json

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200
}

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见 状态码。

批量更新服务器身份组优先级

IM 服务端提供 API 支持指定某个服务器批量更新该服务器的身份组优先级。身份组有优先级高低之分，拥有管理角色权限的高优先级身份组成员，才可修改较低优先级身份组的权限配置。

功能介绍

当用户拥有管理角色权限后，可对优先级低于自身最高优先级身份组的其他身份组进行操作（如修改权限配置），也可创建一个新的自定义身份组，并对其进行优先级排序。新的自定义身份组被创建后，其优先级默认为用户所属自定义身份组中最低。

注意事项

• 调用该方法必须拥有管理角色权限。且当拥有该权限的用户想去变更某个低优先级身份组的某项权限时，首先该用户自身必须有该权限项，即该用户所在的所有身份组中，至少有一个身份组的该权限项的状态为开启。
• 自定义身份优先级永远高于@everyone身份组。
• 修改后的优先级必须在修改前的最高优先级和最低优先级之间。比如，修改前 serverRole1 优先级 p1，serverRole2 优先级 p2，serverRole3 优先级 p3，想把他们的优先级分别改为 P1、P2 和 P3，必须满足 min(P1，P2，P3) >= min(p1，p2，p3)，max(P1，P2，P3) <= max(p1，p2，p3)。

URL

POST  http://api.netease.im/nimserver/qchat/batchUpdateServerIdentifyPriority.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参考 API 调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
accid	String	是	操作者的云信 IM 账号
roleIdPriorities	String	是	服务器身份组 ID 和优先级的列表，JSON 数组（roleId|priority），示例"["12345|2", "45678|1"]" 最佳实践：建议把 priority 为 1 的身份组空出来，不要用在业务上。可以把这个 priority 为 1 的身份组专门留给最高管理员使用，方便后面调整其他身份组的优先级 如果仅填入一个 roleId，将报错（状态码：414）。 如果填入的几个 roleId 里，某个 roleId 不存在，将报错（状态码：403）。 请勿将优先级的数值修改为 0，否则将报错（状态码：403）。0 为 @everyone 身份组的专属优先级数值。
serverId	long	是	服务器 ID

返回参数

参数	类型	说明
code	int	状态码
identifies	String	身份组信息

其中 identifies 包含的参数说明如下：

参数	类型	说明
ext	String	身份组自定义扩展
membercount	Number	身份组成员数量
createtime	Number	创建时间
roleId	long	身份组 ID
auths	String	身份组权限
name	String	身份组名称
icon	String	身份组图标的 URL
priority	String	身份组的优先级，正数。数字越小，优先级越大，最小为1，everyone 身份组为 0，但不参与比较
type	int	身份组类型
updatetime	String	更新时间
ismember	int	当前用户是否在该身份组中， 0-否，1-是

示例

cURL 请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9*****kglw0803mgq3" -H "Nonce: 4tg**ow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962c*****7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&serverIdAccids=%5B%2254321|11%22%2C%2254322|22%22%5D' 'http://api.netease.im/nimserver/qchat/batchUpdateServerIdentifyPriority.action'

返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
    "identifies":[{
        "ext": "ext", //身份组自定义扩展
        "membercount": 1, //身份组成员数量
        "createtime": 1, //创建时间
        "roleId": 1, //身份组ID
        "auths": "{\"1\":-1, \"2\":1}", //身份组权限
        "name": "name", //身份组名称
        "icon": "icon", //身份组图标
        "priority": 1, //身份组优先级
        "type": 1, //身份组类型
        "updatetime": 1, //更新时间
        "ismember": 0 //自己是否在该身份组中，0否1是
    }]
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，状态码列表请参考 状态码。

分页查询服务器身份组

分页查询服务器身份组信息，包括权限项状态、创建时间、更新时间等。

URL

httpPOST https://api.netease.im/nimserver/qchat/getServerIdentifyPages.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参考 API 调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
accid	String	是	操作者的云信 IM 账号（accid）
serverId	String	是	服务器 ID
priority	Long	否	按照**优先级的数值**从小到大排序。查询结果起始的优先级。如果不传或者传 0 默认为首页，首页会返回@everyone 身份组放在返回结果集的首条
limit	Integer	否	每页限制查询多少条，不传时默认为200，最大限制为200
channelId	String	否	可选，以channelId的名义查询。若设置该字段，则只需要有该channel的管理权限即可，否则需要有server的管理权限
categoryId	String	否	可选，以categoryId的名义查询。若设置该字段，则只需要有该channel category的管理权限即可，否则需要有server的管理权限

示例

curl请求示例

curlcurl -X POST -H "AppKey: go9dn**1kglw0803mgq3" -H "Nonce: 4tgggerg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'serverId=1513535&accid="accid"&priority=1&limit=10' 'http://api.netease.im/nimserver/qchat/getServerIdentifyPages.action'

返回示例

http 响应:json

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
	"serverIdentifies":[{
		"ext": "ext",//扩展字段
		"membercount": 1,//身份组的成员数
		"createtime": 1,//创建时间
		"roleId": 1,//身份组的唯一标识
		"auths": "{\"1\":-1, \"2\":1}",//身份组的权限。key为权限项的枚举值，value为 1 时表示“开启”，为 -1 表示“关闭”，服务器身份组的权限状态只有“开启”和“关闭”
		"name": "name",//身份组名称
		"icon": "icon",//身份组图标url
		"priority": 1,//身份组的优先级，优先级数字越小优先级越高，1 为最高。@everyone为默认身份组，优先级的值为0，不参与其他身份组的比较
		"type": 1,//身份组的类型1：@everyone身份组，2：自定义身份组
		"updatetime": 1,//更新时间
		"ismember": 0//操作者是否属于服务器成员，0不属于，1属于
	}]
}

@everyone 身份组不返回 membercount 和 isMember。

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见 状态码。