====== 群组管理 ======

----

环信提供了 REST API 来管理 APP 中的群组。

单个APP创建群组数量有[[http://www.easemob.com/pricing/im|限制]]，如需增加可根据具体业务联系商务解决。单用户ID只能加入500个群。

 ===== 群组数据结构 =====

^字段名	^类型 ^描述^
|id	|String |群组 ID，群组唯一标识符，由环信服务器生成，等同于单个用户的环信 ID。|
|name	|String	|群组名称，根据用户输入创建，字符串类型。|
|description	|String	|群组描述，根据用户输入创建，字符串类型。|
|public	|Boolean	|群组类型：true：公开群，false：私有群。|
|membersonly	|Boolean  	|加入群组是否需要群主或者群管理员审批。true：是，false：否。|
|allowinvites	|Boolean	|是否允许群成员邀请别人加入此群。 true：允许群成员邀请人加入此群，false：只有群主才可以往群里加人。|
|maxusers	|Integer	|群成员上限，创建群组的时候设置，可修改。|
|affiliations_count	|Integer	|现有成员总数。|
|affiliations	|Array	|现有成员列表，包含了 owner 和 member。例如："affiliations":[{"owner": "13800138001"},{"member":"v3y0kf9arx"},{"member":"xc6xrnbzci"}]。|
|owner	|String	|群主的环信 ID。例如：{"owner": "13800138001"}。|
|member	|String	|群成员的环信 ID。例如：{"member":"xc6xrnbzci"}。|
|invite_need_confirm|Boolean|邀请加群，被邀请人是否需要确认。如果是true，表示邀请加群需要被邀请人确认；如果是false，表示不需要被邀请人确认，直接将被邀请人加入群。 该字段的默认值为true。|

===== 群组角色 =====

群组除了群主、普通群成员之外，新增群管理员角色。

群组角色权限范围：群主 > 群管理员 > 普通群成员

  * 群主拥有群的所有权限；
  * 群管理员拥有管理黑名单、禁言等权限。

===== 管理群组 =====

==== 分页获取 APP 下的群组 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups
  * HTTP Method: GET
  * URL Params: limit 预期获取的记录数，数字类型; cursor　游标，如果数据还有下一页，API 返回值会包含此字段，字符类型。
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

=== 第一页 ===

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups?limit=2"
</code>

Response 示例：

<code json>
{
    "action": "get",
    "params": {
        "limit": [
            "2"
        ]
    },
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups",
    "entities": [],
    "data": [
        {
            "owner": "easemob-demo#chatdemoui_user001",
            "groupid": "100743775617286960",
            "affiliations": 2,
            "type": "group",
            "last_modified": "1441021038124",
            "groupname": "user001g"
        },
        {
            "owner": "easemob-demo#chatdemoui_hxt004",
            "groupid": "100973270123152176",
            "affiliations": 1,
            "type": "group",
            "last_modified": "1441074471486",
            "groupname": "hxt004ht"
        }
    ],
    "timestamp": 1441094193812,
    "duration": 14,
    "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z",
    "count": 2
}
</code>

=== 第二页 ===

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups?limit=10&cursor=Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z"
</code>


Response 示例：

<code json>
{
    "action": "get",
    "params": {
        "cursor": [
            "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z"
        ],
        "limit": [
            "2"
        ]
    },
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups",
    "entities": [],
    "data": [
        {
            "owner": "easemob-demo#chatdemoui_jianxin1",
            "groupid": "1432966654513221",
            "affiliations": 3,
            "type": "group",
            "last_modified": "1438605276924",
            "groupname": "testrestgrp12"
        },
        {
            "owner": "easemob-demo#chatdemoui_jianxin1",
            "groupid": "1432966654926530",
            "affiliations": 3,
            "type": "group",
            "last_modified": "1432966654927",
            "groupname": "testrestgrp11"
        }
    ],
    "timestamp": 1441094237757,
    "duration": 580,
    "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV81",
    "count": 2
}
</code>

==== 获取一个用户参与的所有群组 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/joined_chatgroups
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略
  * 可能的错误码：404（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]


curl 示例：
<code php>
curl -X GET 'https://a1.easemob.com/easemob-demo/chatdemoui/users/kenshinn/joined_chatgroups' -H 'Authorization: Bearer YWMtF4ZxXlLmEeS7kWnCMObSnQAAAUo-7HZU-bP7-SJzYGCaUdumxsGelt8pmss'
</code>


Response 示例：

<code json>
{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/kenshinn/joined_chatgroups",
  "entities" : [ ],
  "data" : [ {
    "groupid" : "1413193977786197",
    "groupname" : "kenshingrou"
  }, {
    "groupid" : "1413194058403881",
    "groupname" : "kenshinngr1"
  }, {
    "groupid" : "1413601924284",
    "groupname" : "kenshinngroup002"
  }, {
    "groupid" : "1413026100974",
    "groupname" : "18192976732 的地图"
  }, {
    "groupid" : "141327925742855",
    "groupname" : "kenshinngro"
  }, {
    "groupid" : "1413211974686981",
    "groupname" : "5cxhactgdjgr"
  } ],
  "timestamp" : 1413428676499,
  "duration" : 80
}
</code>

==== 获取群组详情 ====

可以获取一个或多个群组的详情。当获取多个群组的详情时，会返回所有存在的群组的详情，对于不存在的群组，response body内返回"group id doesn't exist"。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id1},{group_id2}
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE"  -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1410511142870,1408518613503"
</code>

Response 示例：

<code json>
{
  "action" : "get",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1410511142870,1408518613503",
  "entities" : [ ],
  "data" : [ {
    "id" : "1408518613503",
    "name" : "Jay13800138000",
    "description" : "",
    "public" : false,
    "membersonly" : true,
    "allowinvites" : false,
    "maxusers" : 200,
    "affiliations_count" : 3,
    "affiliations" : [ {
      "owner" : "13800138001"
     }, {
      "member" : "v3y0kf9arx"
     }, {
      "member" : "xc6xrnbzci"
     } ]
   }, {
    "id" : "1410511142870",
    "name" : "abc",
    "description" : "",
    "public" : false,
    "membersonly" : true,
    "allowinvites" : false,
    "maxusers" : 200,
    "affiliations_count" : 1,
    "affiliations" : [ {
      "owner" : "u366"
    } ]
  } ],
  "timestamp" : 1411526263806,
  "duration" : 34,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 创建一个群组 ====

创建一个群组，并设置群组名称、群组描述、公开群/私有群属性、群成员最大人数（包括群主）、加入公开群是否需要批准、群主、以及群成员。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 
<code json>
{
    "groupname":"testrestgrp12", //群组名称，此属性为必须的
    "desc":"server create group", //群组描述，此属性为必须的
    "public":true, //是否是公开群，此属性为必须的
    "maxusers":300, //群组成员最大数（包括群主），值为数值类型，具体限制请参考价格页
    "members_only":true // 加入群是否需要群主或者群管理员审批，默认是false
    "allowinvites": true  //是否允许群成员邀请别人加入此群。 true：允许群成员邀请人加入此群，false：只有群主或者管理员才可以往群里加人。
    "owner":"jma1", //群组的管理员，此属性为必须的
    "members":["jma2","jma3"] //群组成员，此属性为可选的，但是如果加了此项，数组元素至少一个（注：群主jma1不需要写入到members里面）
}
</code>

  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（owner不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]


curl 示例：

<code php>
curl -X POST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw45TXUWSIrXI8' -d '{"groupname":"testrestgrp12","desc":"server create group","public":true,"approval":true,"owner":"2ewcgkhhxf","maxusers":300,"members":["zh9w1hc49q"]}'
</code>


Response 示例：

<code json>
{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "groupid" : "1411527886490154"
  },
  "timestamp" : 1411527886457,
  "duration" : 125,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 修改群组信息 ====

修改成功的数据行会返回 true，失败为 false。请求 body 只接收 groupname、description、maxusers　三个属性，传不存在的字段，或者不能修改的字段会抛异常。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}
  * HTTP Method: PUT
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 
<code json>
{
    "groupname":"test rest group", //群组名称，修改时值不能包含斜杠（"/"）。
    "description":"update group info", //群组描述，修改时值不能包含斜杠（"/"）。
    "maxusers":300 //群组成员最大数（包括群主），值为数值类型
}
</code>
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X PUT 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1412957434136' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIrXI8' -d '{"groupname":"testrestgrp12","description":"update groupinfo","maxusers":400}'
</code>

Response 示例：

<code json>
{
  "action" : "put",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "maxusers" : true,
    "groupname" : true,
    "description":true
  },
  "timestamp" : 1419565633183,
  "duration" : 30,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 删除群组 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411527886490154' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw45TXUWSIrXI8'
</code>


Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "success" : true,
    "groupid" : "1411527886490154"
  },
  "timestamp" : 1411528112078,
  "duration" : 15,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

===== 管理群组成员 =====

==== 分页获取群组成员 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/users
  * HTTP Method: GET
  * URL Params: pagenum：页码，从1开始；pagesize: 每页显示数量，最大不超过1000
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

curl 示例：

<code>
curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/users?pagenum=2&pagesize=2 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例：

<code json>
	 {
	  "action": "get",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "params": {
	    "pagesize": [
	      "2"
	    ],
	    "pagenum": [
	      "2"
	    ]
	  },
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/users",
	  "entities": [],
	  "data": [
	    {
	      "member": "user1"
	    },
	    {
	      "member": "user2"
	    }
	  ],
	  "timestamp": 1489074511416,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui",
	  "count": 2
	}
</code>
==== 添加群组成员[单个] ====

一次给群添加一个成员，不同重复添加同一个成员。如果用户已经是群成员，将添加失败，并返回错误。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/{username}
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略
  * 可能的错误码：400（被添加的IM用户不存在）、403（IM用户已经是群成员）、404（此群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]


curl 示例：
<code php>
curl -X POST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users/q4xpsfjfvf' -H 'Authorization: Bearer YWMtgNIiTFAwEeSB9olyTIXFtwAAAUotKvWaUOaUuqeuhNMgOgozO4popVZe-Ls'
</code>


Response 示例：
<code json>
{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "action" : "add_member",
    "result" : true,
    "groupid" : "1411816013089",
    "user" : "q4xpsfjfvf"
  },
  "timestamp" : 1413012512005,
  "duration" : 29,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 添加群组成员[批量] ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{chatgroupid}/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: {“usernames”:[“username1”,”username2”]}’ — usernames 固定属性，作为 JSON 的 KEY；username1/username2 要添加到群中的成员用户名，可变
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略
  * 可能的错误码：400（用户不存在）、403（所有用户均已是群成员）、404（群组id不存在、添加owner为member）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]


curl 示例：

<code php>
curl -X  POST -H 'Authorization: Bearer YWMtF4ZxXlLmEeS7kWnCMObSnQAAAUo-7HZU-bP7-SJzYGCaUdumxsGelt8pmE4' -i  'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users' -d '{"usernames":["5cxhactgdj","mh2kbjyop1"]}'
</code>

Response 示例：

<code json>
{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "newmembers" : [ "5cxhactgdj", "mh2kbjyop1" ],
    "action" : "add_member",
    "groupid" : "1411816013089"
  },
  "timestamp" : 1413428995083,
  "duration" : 4,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 移除群组成员[单个] ====


从群中移除某个成员。如果被移除用户不是群成员，将移除失败，并返回错误。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/{username}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略
  * 可能的错误码：403（被移除用户不在群组里等）、404（被移除的IM用户不存在，此群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users/q4xpsfjfvf' -H 'Authorization: Bearer YWMtgNIiTFAwEeSB9olyTIXFtwAAAUotKvWaUOaUuqeuhNMgOgozO4popVZe-Ls'
</code>


Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "action" : "remove_member",
    "result" : true,
    "groupid" : "1411816013089",
    "user" : "q4xpsfjfvf"
  },
  "timestamp" : 1413012566573,
  "duration" : 56,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>


==== 移除群组成员[批量] ====

移除群成员，用户名之间用英文逗号分隔。如果所有被移除用户均不是群成员，将移除失败，并返回错误。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/memeber1,member2,member3
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {"Content-Type":"application/json","Authorization":"Bearer ${token}"}
  * Request Body: 无
  * Response Body: result 为 true 表示移除成功；result 为 false 表示移除失败，此时 reason 字段注明失败原因。
  * 可能的错误码：403（被移除用户不在群组里等）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1433495614983/users/user1,user2,user3"
</code>

Response 示例：

<code json>
{
            "action": "delete",
            "application": "9b848cf0-fafe-11e4-b5b8-0f74e8e740f7",
            "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
            "entities": [],
            "data": [
                {
                    "result": false,
                    "action": "remove_member",
                    "reason": "user ttestuser0015981 doesn't exist.",
                    "user": "user1",
                    "groupid": "1433492852257879"
                },
                {
                    "result": true,
                    "action": "remove_member",
                    "user": "user2",
                    "groupid": "1433492852257879"
                },
                {
                    "result": true,
                    "action": "remove_member",
                    "user": "user3",
                    "groupid": "1433492852257879"
                }
            ],
            "timestamp": 1433492935318,
            "duration": 84,
            "organization": "easemob-demo",
            "applicationName": "chatdemoui"
} 
</code>

==== 获取群管理员列表 ====

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

curl示例：

<code>
curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例：

<code json>
	{
	  "action": "get",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin",
	  "entities": [],
	  "data": [
	    "z1"
	  ],
	  "timestamp": 1489073361210,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui",
	  "count": 1
	}
</code>

==== 添加群管理员 ====

将一个群成员角色提升为群管理员。

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 参见curl示例
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码
 
curl示例：

<code>
curl -XPOST HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin -d '{"newadmin":"z1"}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例：

<code json>
	{
	  "action": "post",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin",
	  "entities": [],
	  "data": {
	    "result": "success",
	    "newadmin": "z1"
	  },
	  "timestamp": 1489073130083,
	  "duration": 1,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}
</code>

==== 移除群管理员 ====

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

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

curl示例：

<code>
curl -XDELETE HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin/z1 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例：

<code json>
	{
	  "action": "delete",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/admin/z1",
	  "entities": [],
	  "data": {
	    "result": "success",
	    "oldadmin": "z1"
	  },
	  "timestamp": 1489073432732,
	  "duration": 1,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}
</code>
==== 转让群组 ====

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

**注意：**将群组Owner转让给其他群成员后，原群组Owner将变成群成员。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{groupid}
  * HTTP Method: PUT
  * URL Params: 无
  * Request Headers: {"Content-Type":"application/json","Authorization":"Bearer ${token}"}
  * Request Body: {"newowner":"${new_owner_user}"}
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]] 


curl 示例：

<code php>
curl -X PUT -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1433495614983" -d '{"newowner":"username1"}'
</code>

Response 示例：

<code json>
{
        "action": "put",
        "application": "9b848cf0-fafe-11e4-b5b8-0f74e8e740f7",
        "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
        "entities": [],
        "data": {
            "newowner": true
        },
        "timestamp": 1433495614983,
        "duration": 194,
        "organization": "easemob-demo",
        "applicationName": "chatdemoui"
}
</code>

===== 管理黑名单 =====

==== 查询群组黑名单 ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 参见“curl 示例”
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -XGET 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response 示例：

<code json>
{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users",
  "entities": [],
  "data": [
    "hxt001",
    "hxt002",
    "hxt003",
    "hxt004"
  ],
  "timestamp": 1439557362316,
  "duration": 4
}
</code>

==== 添加用户至群组黑名单[单个] ====

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

用户进入群组黑名单后，会收到消息：You are kicked out of the group xxx。之后，该用户查看不到该群组的信息，也收不到该群组的消息。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 参见curl示例
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -XPOST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt002' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response 示例：

<code json>
{
  "action": "post",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_blocks",
    "user": "hxt002",
    "groupid": "91340342439182920"
  },
  "timestamp": 1439557079351,
  "duration": 34,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}
</code>
==== 添加用户至群组黑名单[批量] ====

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

用户进入群组黑名单后，会收到消息：You are kicked out of the group xxx。之后，该用户查看不到该群组的信息，也收不到该群组的消息。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: {"usernames":["username1","username2","username3"]}
  * Response Body: result为true表示添加成功；result为false表示添加失败，此时reason字段注明失败原因。
  * 可能的错误码：404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -XPOST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1' -d '{"usernames":["hxt001","hxt002","hxt003"]}'
</code>

Response 示例：

<code json>
{
  "action": "post",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "add_blocks",
      "reason": "the user hxt001 doesn't exist",
      "user": "hxt001",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "add_blocks",
      "user": "hxt002",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "add_blocks",
      "user": "hxt003",
      "groupid": "91340342439182920"
    }
  ],
  "timestamp": 1439557269929,
  "duration": 190,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}
</code>
==== 从群组黑名单移除用户[单个] ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的json数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -XDELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt001' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response 示例：

<code json>
{
  "action": "delete",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_blocks",
    "user": "hxt001",
    "groupid": "91340342439182920"
  },
  "timestamp": 1439557411653,
  "duration": 13,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}
</code>

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

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username1},{username2}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: result为true表示移除成功；result为false表示移除失败，此时reason字段注明失败原因。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -XDELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt001,hxt002,hxt003' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response 示例：

<code json>
{
  "action": "delete",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt001",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt002",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt003",
      "groupid": "91340342439182920"
    }
  ],
  "timestamp": 1439557455684,
  "duration": 23,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}
</code>

===== 管理禁言 =====

==== 添加禁言 ====

将一个用户禁言。用户被禁言后，将无法在群中发送消息。

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 参见curl示例
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码
 
curl示例：

<code>
curl -XPOST HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute -d '{"usernames":["z1","z2","z3"], "mute_duration":86400000}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

其中，usernames后是被禁言的群用户ID， mute_duration是禁言的时长，单位是毫秒,必须是Integer或者Long类型。

Response示例:

<code json>
	{
	  "action": "post",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute",
	  "entities": [],
	  "data": [
	    {
	      "result": true,
	      "expire": 1489158589481,
	      "user": "z1"
	    },
	    {
	      "result": true,
	      "expire": 1489158589481,
	      "user": "z2"
	    },
	    {
	      "result": true,
	      "expire": 1489158589481,
	      "user": "z3"
	    }
	  ],
	  "timestamp": 1489072189508,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}
</code>

注：expire指的是禁言到期的UNIX时间戳。

==== 移除禁言 ====

将用户从禁言列表中移除。移除后，用户可以正常在群中发送消息。

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute/{member1}(,{member2},...)
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

curl示例：

<code>
curl -XDELETE HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute/z1,z2,z3  -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例:

<code json>
	{
	  "action": "delete",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute/z1,z2,z3",
	  "entities": [],
	  "data": [
	    {
	      "result": true,
	      "user": "z1"
	    },
	    {
	      "result": true,
	      "user": "z2"
	    },
	    {
	      "result": true,
	      "user": "z3"
	    }
	  ],
	  "timestamp": 1489072695859,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}
</code>

==== 获取禁言列表 ====

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

  * Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在）、404（群组id不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：服务器端 REST API 常见错误码

curl示例：

<code>
curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'
</code>

Response示例：

<code json>
	{
	  "action": "post",
	  "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
	  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/mute",
	  "entities": [],
	  "data": [
	    {
	      "expire": 1489158589481,
	      "user": "z3"
	    },
	    {
	      "expire": 1489158589481,
	      "user": "z1"
	    },
	    {
	      "expire": 1489158589481,
	      "user": "z2"
	    }
	  ],
	  "timestamp": 1489072802179,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}
</code>

----
<WRAP group>
<WRAP half column>
上一页：[[im:100serverintegration:50messages|发送消息]]
</WRAP>

<WRAP half column>
下一页：[[im:100serverintegration:70chatroommgmt|聊天室管理]]
</WRAP>
</WRAP>