差别
这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
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> |