差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录 前一修订版
后一修订版
前一修订版
im:server:basics:chatroom [2020/01/14 06:28]
huanxinfudh [管理禁言]
im:server:basics:chatroom [2022/05/19 04:09] (当前版本)
jennifer.zeng [聊天室管理]
行 1: 行 1:
 ====== 聊天室管理 ====== ====== 聊天室管理 ======
 +
 +更新时间:2021-12-31 该文档已不再维护,请看新版 3.X 文档。
 +
 +新版文档见:[[ccim:​rest:​chatroom|聊天室管理]]。
  
 ---- ----
行 5: 行 9:
 环信提供了 REST API 来管理 APP 中的聊天室。 环信提供了 REST API 来管理 APP 中的聊天室。
  
-单个APP创建聊天室数量有[[http://​www.easemob.com/​pricing/​im|限制]],如需增加可根据具体业务联系商务解决。单用户ID只能加入500个聊天室。 
  
 +单个APP可以创建的聊天室数量以及单用户ID可以加入的聊天室数量请参考不同版本[[http://​www.easemob.com/​pricing/​im|数量]],如需增加可根据具体业务联系商务解决。
 ===== 聊天室数据结构 ===== ===== 聊天室数据结构 =====
  
行 27: 行 31:
   * 聊天室创建者拥有聊天室所有权限;   * 聊天室创建者拥有聊天室所有权限;
   * 聊天室管理员拥有添加/​移除黑名单、添加/​移除禁言等权限。   * 聊天室管理员拥有添加/​移除黑名单、添加/​移除禁言等权限。
 +  * 最多管理员角色数量:1个创建者+99个管理员
  
 ---- ----
  
-====== REST API  ======+===== REST API 在线测试说明 ​=====
 IM 聊天室集成过程中,需要使用到的 REST API 文档详细说明,可以通过使用文档中嵌入的[[http://​api-docs.easemob.com/​|Easemob REST API]]进行在线测试。 IM 聊天室集成过程中,需要使用到的 REST API 文档详细说明,可以通过使用文档中嵌入的[[http://​api-docs.easemob.com/​|Easemob REST API]]进行在线测试。
 ===== 管理聊天室 ===== ===== 管理聊天室 =====
行 212: 行 217:
 |owner|聊天室创建者的 username。例如:{“owner”:​ “user1”}。| |owner|聊天室创建者的 username。例如:{“owner”:​ “user1”}。|
 |member|聊天室成员的 username。例如: {“member”:​”user2”}。| |member|聊天室成员的 username。例如: {“member”:​”user2”}。|
-|public|聊天室类型:true:公开聊天室,false:私有聊天室。| 
 |affiliations_count|现有聊天室成员总数。| |affiliations_count|现有聊天室成员总数。|
 |affiliations|现有成员列表,包含了 owner 和 member。例如: “affiliations”:​[{“owner”:​ “user1”},​{“member”:​”user2”},​{“member”:​”user3”}]。| |affiliations|现有成员列表,包含了 owner 和 member。例如: “affiliations”:​[{“owner”:​ “user1”},​{“member”:​”user2”},​{“member”:​”user3”}]。|
行 288: 行 292:
  
 ==== 创建聊天室 ==== ==== 创建聊天室 ====
-创建一个聊天室,并设置聊天室名称、聊天室描述、公开聊天室/​私有聊天室属性、聊天室成员最大人数(包括管理员)、加入公开聊天室是否需要批准、管理员、以及聊天室成员。+创建一个聊天室,并设置聊天室名称、聊天室描述、聊天室成员最大人数(包括管理员)、加入聊天室是否需要批准、管理员、以及聊天室成员。聊天室默认都是公开的
  
 === HTTP Request === === HTTP Request ===
行 305: 行 309:
 |name|聊天室名称,此属性为必须的| |name|聊天室名称,此属性为必须的|
 |description|聊天室描述,此属性为必须的| |description|聊天室描述,此属性为必须的|
-|maxusers|聊天室成员最大数(包括聊天室创建者),值为数值类型,默认值200,最大值5000,此属性为可选的|+|maxusers|聊天室成员最大数(包括聊天室创建者),值为数值类型,此属性为可选的|
 |owner|聊天室的管理员,此属性为必须的| |owner|聊天室的管理员,此属性为必须的|
 |members|聊天室成员,此属性为可选的,但是如果加了此项,数组元素至少一个| |members|聊天室成员,此属性为可选的,但是如果加了此项,数组元素至少一个|
行 820: 行 824:
 ==== 批量删除聊天室成员 ==== ==== 批量删除聊天室成员 ====
 从聊天室删除多个成员。如果被删除用户不在聊天室中,或者聊天室不存在,将返回错误。 从聊天室删除多个成员。如果被删除用户不在聊天室中,或者聊天室不存在,将返回错误。
 +
 +一次最多传100个环信id。
  
 === HTTP Request === === HTTP Request ===
行 1053: 行 1059:
 |添加禁言|/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute|添加用户至聊天室的禁言列表| |添加禁言|/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute|添加用户至聊天室的禁言列表|
 |移除禁言|/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute/​{member1}(,​{member2},​…)|从聊天室的禁言列表中移除用户| |移除禁言|/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute/​{member1}(,​{member2},​…)|从聊天室的禁言列表中移除用户|
 +
 +
 +====添加禁言====
 +将一个用户禁言。用户被禁言后,将无法在聊天室中发送消息。
 +=== HTTP Request ===
 +
 +^{{:​im:​server:​basics:​post.png?​nolink&​90|}}^** /​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute**^
 +需要在请求时对应填写{chatroom_id},需要添加禁言的聊天室 ID 。
 +
 +=== Request Headers ===
 +
 +^参数^说明^
 +|Content-Type|application/​json|
 +|Authorization|Bearer ${token}|
 +
 +=== Request Body ===
 +
 +^参数^说明^
 +|mute_duration|禁言的时间,单位毫秒,如果是“-1”代表永久(实际的到期时间为固定时间戳4638873600000,即2117-01-01 00:​00:​00)|
 +|usernames|要被添加禁言用户的 ID |
 +
 +=== Response Body ===
 +
 +^参数^说明^
 +|result|操作结果;true:添加成功;false:添加失败|
 +|expire|禁言到期的时间戳(从1970年1月1日开始的毫秒数。如果禁言时间传的值为"​-1"​,那么该时间戳为固定的4638873600000,请参考mute_duration参数的说明)|
 +|user|被禁言用户的 ID |
 +
 +=== 请求示例 ===
 +<code php>
 +curl -X POST HTTP://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute -d '​{"​usernames":​["​user1"​],​ "​mute_duration":​86400000}'​ -H '​Authorization:​ Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'​
 +</​code>​
 +=== 可能返回的结果示例 ===
 +**返回值200,表示添加禁言成功**
 +<code json>
 +{
 +    "​action":​ "​post",​
 +    "​application":​ "​527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",​
 +    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute",​
 +    "​entities":​ [],
 +    "​data":​ [{
 +        "​result":​ true,
 +        "​expire":​ 1489158589481,​
 +        "​user":​ "​user1"​
 +    }],
 +    "​timestamp":​ 1489072189508,​
 +    "​duration":​ 0,
 +    "​organization":​ "​easemob-demo",​
 +    "​applicationName":​ "​testapp"​
 +}
 +</​code>​
 +
 +如果返回结果是<​wrap em>​429、503</​wrap>​或者其他<​wrap em>​5xx</​wrap>​,有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:​450errorcode:​45restastrict|接口限流说明]]
 +
 +[[http://​api-docs.easemob.com/​|使用 Easemob REST API 在线测试]]
 +----
 +
 +====移除禁言====
 +将用户从禁言列表中移除。移除后,用户可以正常在聊天室中发送消息。
 +=== HTTP Request ===
 +
 +^{{:​im:​server:​basics:​delete.png?​nolink&​90|}}^**/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute/​{member1}(,​{member2},​…)**^
 +需要在请求时对应填写{chatroom_id},需要移除禁言的聊天室 ID ,以及{member1}(,​{member2},​…,需要移除禁言的用户名。
 +
 +=== Request Headers ===
 +
 +^参数^说明^
 +|Content-Type|application/​json|
 +|Authorization|Bearer ${token}|
 +
 +=== 请求示例 ===
 +<code php>
 +curl -X DELETE HTTP://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute/​user1 ​ -H '​Authorization:​ Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'​
 +</​code>​
 +=== 可能返回的结果示例 ===
 +**返回值200,表示移除禁言成功**
 +<code json>
 +{
 +    "​action":​ "​delete",​
 +    "​application":​ "​527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",​
 +    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute/​user1",​
 +    "​entities":​ [],
 +    "​data":​ [{
 +        "​result":​ true,
 +        "​user":​ "​user1"​
 +    }],
 +    "​timestamp":​ 1489072695859,​
 +    "​duration":​ 0,
 +    "​organization":​ "​easemob-demo",​
 +    "​applicationName":​ "​testapp"​
 +}
 +</​code>​
 +
 +如果返回结果是<​wrap em>​429、503</​wrap>​或者其他<​wrap em>​5xx</​wrap>​,有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:​450errorcode:​45restastrict|接口限流说明]]
 +
 +[[http://​api-docs.easemob.com/​|使用 Easemob REST API 在线测试]]
 +----
  
 ====获取禁言列表==== ====获取禁言列表====
行 1070: 行 1173:
  
 ^参数^说明^ ^参数^说明^
-|expire|禁言到期时间,单位毫秒。“-1000“代表永久禁言|+|expire|禁言到期时间戳(从1970年1月1日开始的毫秒如果禁言时间传的值为"​-1"​,那么该时间戳为固定的4638873600000,请参考mute_duration参数的说明)|
 |user|被禁言用户的 ID | |user|被禁言用户的 ID |
  
行 1092: 行 1195:
         "​expire":​ 1489158589481,​         "​expire":​ 1489158589481,​
         "​user":​ "​user2"​         "​user":​ "​user2"​
-    },+    }],
     "​timestamp":​ 1489072802179,​     "​timestamp":​ 1489072802179,​
     "​duration":​ 0,     "​duration":​ 0,
行 1104: 行 1207:
 [[http://​api-docs.easemob.com/​|使用 Easemob REST API 在线测试]] [[http://​api-docs.easemob.com/​|使用 Easemob REST API 在线测试]]
 ---- ----
 +=====管理超级管理员=====
 +环信提供多个管理聊天室超级管理员的接口,包括获取、添加、移除等。超级管理员身份给予了普通用户创建聊天室的权限,普通用户默认没有权限创建聊天室。
 +^名称^请求^描述^
 +|获取超级管理员列表|/​{org_name}/​{app_name}/​chatrooms/​super_admin|获取超级管理员列表|
 +|添加超级管理员|/​{org_name}/​{app_name}/​chatrooms/​super_admin|添加用户至超级管理员列表|
 +|移除超级管理员|/​{org_name}/​{app_name}/​chatrooms/​super_admin/​{superAdmin}|从超级管理员列表列表中移除用户|
  
-====添加禁言==== +====分页获取聊天室超级管理员列表==== 
-将一个用户禁言。用户被禁言后,将无法在聊天室中发送消息+可以分页获取聊天室超级管理员列表的接口
 === HTTP Request === === HTTP Request ===
  
-^{{:​im:​server:​basics:​post.png?​nolink&​90|}}^** /​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute**^ +^{{:​im:​server:​basics:​get.png?​nolink&​90|}}^**/​{org_name}/​{app_name}/​chatrooms/​super_admin**^ 
-需要在请求时对应填写{chatroom_id},需要添加禁言的聊天室 ​ID + 
 +=== Request Headers === 
 + 
 +^参数^说明^ 
 +|Content-Type|application/​json| 
 +|Authorization|Bearer ${token}| 
 + 
 +=== Response Body === 
 + 
 +^参数^说明^ 
 +|data|聊天室超级管理员ID列表 | 
 + 
 +=== 请求示例 === 
 +<code php> 
 +curl -X GET http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​super_admin?​pagenum=2&​pagesize=2 -H '​Authorization:​ Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'​ 
 +</​code>​ 
 + 
 +=== 可能返回的结果示例 === 
 +**返回值200,表示获取聊天室成员成功** 
 +<code json> 
 +{ 
 +    "​action":​ "​get",​ 
 +    "​application":​ "​9fa492a0-40b1-11e5-b1b9-a76b05da6904",​ 
 +    "​params":​ { 
 +        "​pagesize":​ [ 
 +            "​2"​ 
 +        ], 
 +        "​pagenum":​ [ 
 +            "​2"​ 
 +        ] 
 +    ​}
 +    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​super_admin",​ 
 +    "​entities":​ [], 
 +    "​data":​ [ 
 +        "​hxtest1",​ 
 +        "​hxtest11",​ 
 +        "​hxtest10"​ 
 +    ], 
 +    "​timestamp":​ 1596187292391,​ 
 +    "​duration":​ 0, 
 +    "​organization":​ "​easemob-demo",​ 
 +    "​applicationName":​ "​testapp",​ 
 +    "​count":​ 3 
 +
 +</​code>​ 
 + 
 +如果返回结果是<​wrap em>​429、503</​wrap>​或者其他<​wrap em>​5xx</​wrap>​有可能代表该接口被限流了,请稍微暂停一下并重试。详见[[im:​450errorcode:​45restastrict|接口限流说明]] 
 + 
 +[[http://​api-docs.easemob.com/​|使用 Easemob REST API 在线测试]] 
 +---- 
 + 
 +==== 添加超级管理员 ==== 
 +给用户添加聊天室超级管理员身份 
 + 
 +=== HTTP Request === 
 + 
 +^{{:​im:​server:​basics:​post.png?​nolink&​90|}}^**/​{org_name}/​{app_name}/​chatrooms/​super_admin**^
  
 === Request Headers === === Request Headers ===
行 1121: 行 1286:
  
 ^参数^说明^ ^参数^说明^
-|mute_duration|禁言的时间,单位毫秒,如果是“-1000”代表永久| +|superadmin|添加用户名称|
-|usernames|要被添加禁言用户的 ID |+
  
 === Response Body === === Response Body ===
 +在返回值中查看data字段包含的信息
 ^参数^说明^ ^参数^说明^
-|result|操作结果true添加成功false添加失败+|result|添加结果true表示添加成功false表示添加失败|
-|expire|禁言到期时间,​单位毫秒。“-1000“代表永久禁言| +
-|user|被禁言用户的 ID |+
  
 === 请求示例 === === 请求示例 ===
 <code php> <code php>
-curl -X POST HTTP://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute ​-d '​{"​usernames":["user1"], "​mute_duration":​86400000}' -H '​Authorization:​ Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'+curl -X POST -H '​Content-Type:​ application/​json'​ -H '​Accept:​ application/​json'​ -H '​Authorization:​ Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ'​ 'http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​super_admin' ​-d '​{"​superadmin":"​u1"​}'​
 </​code>​ </​code>​
 === 可能返回的结果示例 === === 可能返回的结果示例 ===
-**返回值200,表示添加禁言成功**+**返回值200,表示聊天室成员添加成功**
 <code json> <code json>
 { {
     "​action":​ "​post",​     "​action":​ "​post",​
-    "​application":​ "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0", +    "​application":​ "9fa492a0-40b1-11e5-b1b9-a76b05da6904", 
-    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/1265710621211/mute",+    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​hxdemo2/chatrooms/super_admin",
     "​entities":​ [],     "​entities":​ [],
-    "​data": ​[+    "​data":​ { 
-        "​result": ​true, +        "​result":​ "success", 
-        ​"expire": 1489158589481+        "resource": ""​ 
-        "user": "user1+    }, 
-    }]+    "​timestamp": ​1596187658017
-    "​timestamp": ​1489072189508+    "​duration": ​1,
-    "​duration": ​0,+
     "​organization":​ "​easemob-demo",​     "​organization":​ "​easemob-demo",​
     "​applicationName":​ "​testapp"​     "​applicationName":​ "​testapp"​
 +}
 +</​code>​
 +
 +**返回值404,表示添加的用户或聊天室不存在**
 +<code json>
 +{
 +  "​error":​ "​resource_not_found",​
 +  "​timestamp":​ 1542554114398,​
 +  "​duration":​ 0,
 +  "​exception":​ "​com.easemob.group.exception.ResourceNotFoundException",​
 +  "​error_description":​ "​username user10 doesn'​t exist!"​
 +}
 +</​code>​
 +
 +**返回值401,未授权[无token、token错误、token过期]**
 +<code json>
 +{
 +  "​error":​ "​group_authorization",​
 +  "​timestamp":​ 1542554229364,​
 +  "​duration":​ 0,
 +  "​exception":​ "​com.easemob.group.exception.GroupAuthorizationException",​
 +  "​error_description":​ "this token is bad, or has expired!"​
 } }
 </​code>​ </​code>​
行 1160: 行 1343:
 ---- ----
  
-====移除禁言==== +==== 移除超级管理员 ​==== 
-将用户从禁言列表中移除。移除后,用户可以正常在聊天室中发送消息。+移除超级管理员 
 === HTTP Request === === HTTP Request ===
  
-^{{:​im:​server:​basics:​delete.png?​nolink&​90|}}^**/​{org_name}/​{app_name}/​chatrooms/​{chatroom_id}/​mute/{member1}(,​{member2},​…)**^ +^{{:​im:​server:​basics:​delete.png?​nolink&​90|}}^**/​{org_name}/​{app_name}/​chatrooms/​super_admin/{superAdmin}**^ 
-需要在请求时对应填写{chatroom_id},需要移除禁言的聊天室 ID ,以及{member1}(,​{member2},…,需要禁言的用户名。+需要在请求时对应填写{superAdmin},需要除的 ​IM 用户名。
  
 === Request Headers === === Request Headers ===
行 1175: 行 1359:
 === 请求示例 === === 请求示例 ===
 <code php> <code php>
-curl -X DELETE ​HTTP://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/​mute/​user1 ​ -H '​Authorization:​ Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'+curl -X DELETE ​-H '​Accept:​ application/​json'​ -H '​Authorization:​ Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ'​ 'http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​super_admin/​user1'​
 </​code>​ </​code>​
 === 可能返回的结果示例 === === 可能返回的结果示例 ===
-**返回值200,表示禁言成功**+**返回值200,表示聊天室成员删除成功**
 <code json> <code json>
 { {
     "​action":​ "​delete",​     "​action":​ "​delete",​
-    "​application":​ "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0", +    "​application":​ "9fa492a0-40b1-11e5-b1b9-a76b05da6904", 
-    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​1265710621211/mute/user1",+    "​uri":​ "​http://​a1.easemob.com/​easemob-demo/​testapp/​chatrooms/​super_admin/hxtest10",
     "​entities":​ [],     "​entities":​ [],
-    "​data": ​[+    "​data":​ { 
-        "result": ​true+        "newSuperAdmin": ​"​user1"​
-        "user": "user1+        "resource": ""​ 
-    }]+    }, 
-    "​timestamp": ​1489072695859,+    "​timestamp": ​1596187855832,
     "​duration":​ 0,     "​duration":​ 0,
     "​organization":​ "​easemob-demo",​     "​organization":​ "​easemob-demo",​
     "​applicationName":​ "​testapp"​     "​applicationName":​ "​testapp"​
 +}
 +</​code>​
 +
 +**返回值401,未授权[无token、token错误、token过期]**
 +<code json>
 +{
 +  "​error":​ "​group_authorization",​
 +  "​timestamp":​ 1542555910183,​
 +  "​duration":​ 0,
 +  "​exception":​ "​com.easemob.group.exception.GroupAuthorizationException",​
 +  "​error_description":​ "this token is bad, or has expired!"​
 } }
 </​code>​ </​code>​