聊天室管理

更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。

环信提供了 REST API 来管理 APP 中的聊天室。

单个APP可以创建的聊天室数量以及单用户ID可以加入的聊天室数量请参考不同版本数量，如需增加可根据具体业务联系商务解决。

聊天室数据结构

名称	类型	描述
id	String	聊天室 ID，聊天室唯一标识符，由环信服务器生成。
name	String	聊天室名称，任意字符串。
description	String	聊天室描述，任意字符串。
maxusers	Integer	聊天室成员上限，创建聊天室的时候设置，可修改。
affiliations_count	Integer	现有成员总数。
affiliations	Array	现有成员列表，包含了 owner 和 member。例如： “affiliations”:[{“owner”: “13800138001”},{“member”:”v3y0kf9arx”},{“member”:”xc6xrnbzci”}]。
owner	String	聊天室创建者的 username。例如：{“owner”: “13800138001”}。
member	String	聊天室成员的 username。例如： {“member”:”xc6xrnbzci”}。

聊天室角色

除了聊天室创建者（owner）、普通聊天室成员之外，新增聊天室管理员角色。

聊天室角色权限范围：创建者 > 聊天室管理员 > 普通聊天室成员

聊天室创建者拥有聊天室所有权限；
聊天室管理员拥有添加/移除黑名单、添加/移除禁言等权限。
最多管理员角色数量：1个创建者+99个管理员

REST API 在线测试说明

IM 聊天室集成过程中，需要使用到的 REST API 文档详细说明，可以通过使用文档中嵌入的Easemob REST API进行在线测试。

管理聊天室

环信提供多个接口完成聊天室相关的集成，包括对聊天室的创建、获取、修改、删除等管理功能。

名称	请求	描述
获取 APP 中所有的聊天室	/{org_name}/{app_name}/chatrooms	获取应用下全部的聊天室信息
获取用户加入的聊天室	/{org_name}/{app_name}/users/{username}/joined_chatrooms	根据用户名称获取此用户加入的全部聊天室
获取聊天室详情	/{org_name}/{app_name}/chatrooms/{chatroom_id}	根据聊天室ID获取此聊天室的详情
创建一个聊天室	/{org_name}/{app_name}/chatrooms	创建一个新聊天室
修改聊天室信息	/{org_name}/{app_name}/chatrooms/{chatroom_id}	修改聊天室的部分信息
删除聊天室	/{org_name}/{app_name}/chatrooms/{chatroom_id}	删除一个聊天室

获取 APP 中所有的聊天室

获取应用下全部的聊天室信息的接口

HTTP Request

	/{org_name}/{app_name}/chatrooms

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息。

参数	说明
id	聊天室 ID，聊天室唯一标识符，由环信服务器生成。
name	聊天室名称，任意字符串。
owner	聊天室创建者的 username。例如：{“owner”: “user1”}。
affiliations_count	现有聊天室成员总数。

请求示例

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms'

可能返回的结果示例

返回值200，表示聊天室获取成功

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1",
      "owner": "user1",
      "affiliations_count": 2
    },
    {
      "id": "66211882795010",
      "name": "testchatroom2",
      "owner": "user2",
      "affiliations_count": 2
    }
  ],
  "timestamp": 1542543050037,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp",
  "count": 2
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542543133343,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取用户加入的聊天室

根据用户名称获取该用户加入的全部聊天室接口

HTTP Request

	/{org_name}/{app_name}/users/{username}/joined_chatrooms

需要在请求时对应填写{username}，需要设获取的 IM 用户名

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息。

参数	说明
id	聊天室 ID，聊天室唯一标识符，由环信服务器生成。
name	聊天室名称，任意字符串。

请求示例

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/joined_chatrooms'

可能返回的结果示例

返回值200，表示聊天室获取成功

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/joined_chatrooms",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1"
    },
    {
      "id": "66211882795010",
      "name": "testchatroom2"
    }
  ],
  "timestamp": 1542543479121,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp",
  "count": 2
}

返回值404，此用户不存在

{
  "error": "resource_not_found",
  "timestamp": 1542543527326,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542543599009,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取聊天室详情

可以获取一个或多个聊天室的详情。当获取多个聊天室的详情时，会返回所有存在的聊天室的详情，对于不存在的聊天室，response body内返回“chatroom id doesn't exist”。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}

需要在请求时对应填写{chatroom_id}，需要获取的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息

参数	说明
id	聊天室 ID，聊天室唯一标识符，由环信服务器生成。
name	聊天室名称，任意字符串。
description	聊天室描述，任意字符串。
membersonly	加入聊天室是否需要群主或者群管理员审批。true：是，false：否。
allowinvites	是否允许聊天室成员邀请别人加入此聊天室。 true：允许聊天室成员邀请人加入此聊天室，false：只有聊天室管理员才可以往聊天室加人。
maxusers	聊天室成员上限，创建聊天室的时候设置，可修改。
owner	聊天室创建者的 username。例如：{“owner”: “user1”}。
member	聊天室成员的 username。例如： {“member”:”user2”}。
affiliations_count	现有聊天室成员总数。
affiliations	现有成员列表，包含了 owner 和 member。例如： “affiliations”:[{“owner”: “user1”},{“member”:”user2”},{“member”:”user3”}]。

请求示例

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913'

可能返回的结果示例

返回值200，表示聊天室详情获取成功

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1",
      "description": "test",
      "membersonly": false,
      "allowinvites": false,
      "maxusers": 200,
      "owner": "user1",
      "created": 1542542951527,
      "custom": "",
      "affiliations_count": 2,
      "affiliations": [
        {
          "member": "user2"
        },
        {
          "owner": "user1"
        }
      ],
      "public": true
    }
  ],
  "timestamp": 1542543844873,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp",
  "count": 1
}

返回值404，此聊天ID不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542543915642,
  "duration": 0,
  "exception": "com.easemob.group.exception.ServiceResourceNotFoundException",
  "error_description": "do not find this group:6621186077491"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542543956477,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

创建聊天室

创建一个聊天室，并设置聊天室名称、聊天室描述、聊天室成员最大人数（包括管理员）、加入聊天室是否需要批准、管理员、以及聊天室成员。聊天室默认都是公开的。

HTTP Request

	/{org_name}/{app_name}/chatrooms

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
name	聊天室名称，此属性为必须的
description	聊天室描述，此属性为必须的
maxusers	聊天室成员最大数（包括聊天室创建者），值为数值类型，此属性为可选的
owner	聊天室的管理员，此属性为必须的
members	聊天室成员，此属性为可选的，但是如果加了此项，数组元素至少一个

Response Body

在返回值中查看data字段包含的信息。

参数	说明
id	所创建的聊天室的 ID

请求示例

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{ 
   "name": "testchatroom1",  
   "description": "test",  
   "maxusers": 300,  
   "owner": "user1",  
   "members": [  
     "user2"  
   ]  
 }' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms'

可能返回的结果示例

返回值200，表示聊天室创建成功

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms",
  "entities": [],
  "data": {
    "id": "66213271109633"
  },
  "timestamp": 1542544296075,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，该聊天室管理员或成员不存在

{
  "error": "resource_not_found",
  "timestamp": 1542544372951,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542544470520,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

修改聊天室信息

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

如果聊天室不存在，会返回错误。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}

需要在请求时对应填写{chatroom_id}，需要修改的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
name	聊天室名称，修改时值不能包含斜杠(“/”)
description	聊天室描述，修改时值不能包含斜杠(“/”)
maxusers	聊天室成员最大数（包括聊天室创建者），值为数值类型

Response Body

在返回值中查看data字段包含的信息

参数	说明
groupname	聊天室名称，true表示修改成功，false表示修改失败
description	聊天室描述，true表示修改成功，false表示修改失败
maxusers	聊天室成员最大数（包括聊天室创建者），true表示修改成功，false表示修改失败

请求示例

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{  
   "name": "testchatroom",  
   "description": "test",  
   "maxusers": 300  
 }' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913'

可能返回的结果示例

返回值200，表示聊天室信息修改成功

{
  "action": "put",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": {
    "description": true,
    "maxusers": true,
    "groupname": true
  },
  "timestamp": 1542544817352,
  "duration": 69,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值403，表示修改最大成员数不符合要求

{
  "error": "forbidden_op",
  "timestamp": 1542544871049,
  "duration": 0,
  "exception": "com.easemob.group.exception.ForbiddenOpException",
  "error_description": "current user count is larger than the maxUsers that you want to update !"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542544961403,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

删除聊天室

删除单个聊天室。如果被删除的聊天室不存在，会返回错误。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}

需要在请求时对应填写{chatroom_id}，需要删除的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913'

可能返回的结果示例

返回值200，表示聊天室删除成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": {
    "success": true,
    "id": "66211860774913"
  },
  "timestamp": 1542545100474,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示该聊天室ID不存在

{
  "error": "resource_not_found",
  "timestamp": 1542545148716,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621186077491 does not exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542545181581,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

管理聊天室成员

环信提供多个接口实现对聊天室成员的管理，包括添加、移除聊天室成员关系列表等

名称	请求	描述
分页获取聊天室成员	/{org_name}/{app_name}/chatrooms/{chatroom_id}/users	分页获取一个聊天室的成员列表
添加单个聊天室成员	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	添加用户至聊天室成员列表
批量添加聊天室成员	/{org_name}/{app_name}/chatrooms/{chatroomid}/users	批量添加用户至聊天室成员列表
删除单个聊天室成员	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	从聊天室成员列表中删除用户
批量删除聊天室成员	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}	从聊天室成员列表中批量删除用户
获取聊天室管理员列表	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	获取聊天室管理员列表
添加聊天室管理员	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	添加用户至聊天室管理员列表
移除聊天室管理员	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}	从聊天室管理员列表中移除用户

分页获取聊天室成员

可以分页获取聊天室成员列表的接口。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/users

需要在请求时对应填写{chatroom_id}，需要获取的聊天室 ID

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

参数	说明
member	聊天室成员 ID

请求示例

curl -X GET http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/users?pagenum=2&pagesize=2 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示获取聊天室成员成功

{
    "action": "get",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "params": {
        "pagesize": ["2"],
        "pagenum": ["2"]
    },
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/users",
    "entities": [],
    "data": [{
        "member": "user1"
    },
    {
        "member": "user2"
    }],
    "timestamp": 1489074511416,
    "duration": 0,
    "organization": "easemob-demo",
    "applicationName": "testapp",
    "count": 2
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

添加单个聊天室成员

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

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}

需要在请求时对应填写{chatroomid}，需要添加的聊天室的 ID ，以及{username}，需要添加的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息

参数	说明
result	添加结果，true表示添加成功，false表示添加失败
action	执行的操作，add_member表示向聊天室添加成员
id	聊天室 ID，聊天室唯一标识符，由环信服务器生成。
user	添加到聊天室的用户

请求示例

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/66213271109633/users/user1'

可能返回的结果示例

返回值200，表示聊天室成员添加成功

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_member",
    "id": "66213271109633",
    "user": "user1"
  },
  "timestamp": 1542554038353,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示添加的用户或聊天室不存在

{
  "error": "resource_not_found",
  "timestamp": 1542554114398,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542554229364,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

批量添加聊天室成员

向聊天室添加多位用户，一次性最多可添加60位用户。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroomid}/users

需要在请求时对应填写{chatroomid}，需要添加的聊天室的 ID ，以及{username}，需要添加的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
usernames	添加的用户名称

Response Body

在返回值中查看data字段包含的信息

参数	说明
usernames	添加的用户名称

请求示例

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{  
   "usernames": [  
     "user1","user2"  
   ]  
 }' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users'

可能返回的结果示例

返回值200，表示聊天室成员添加成功

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users",
  "entities": [],
  "data": {
    "newmembers": [
      "user1",
      "user2"
    ],
    "action": "add_member",
    "id": "66213271109633"
  },
  "timestamp": 1542554537237,
  "duration": 9,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示添加的用户或聊天室不存在

{
  "error": "resource_not_found",
  "timestamp": 1542554590006,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542554611900,
  "duration": 1,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

删除单个聊天室成员

从聊天室删除一个成员。如果被删除用户不在聊天室中，或者聊天室不存在，将返回错误。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}

需要在请求时对应填写{username}，需要删除的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users/user1'

可能返回的结果示例

返回值200，表示聊天室成员删除成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_member",
    "user": "user1",
    "id": "66213271109633"
  },
  "timestamp": 1542555744726,
  "duration": 1,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示该聊天室ID不存在

{
  "error": "resource_not_found",
  "timestamp": 1542555822284,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

返回值403，表示删除的用户不存在

{
  "error": "resource_not_found",
  "timestamp": 1542555822284,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542555910183,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

批量删除聊天室成员

从聊天室删除多个成员。如果被删除用户不在聊天室中，或者聊天室不存在，将返回错误。

一次最多传100个环信id。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}

需要在请求时对应填写{usernames}，需要删除的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users/user1%2Cuser2'

可能返回的结果示例

返回值200，表示聊天室成员删除成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/66213271109633/users/user1%2Cuser2",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "remove_member",
      "reason": "user: user1 doesn't exist in group: 66213271109633",
      "user": "user1",
      "id": "66213271109633"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user2",
      "id": "66213271109633"
    }
  ],
  "timestamp": 1542556177147,
  "duration": 0,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示该聊天室ID不存在

{
  "error": "resource_not_found",
  "timestamp": 1542556220010,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

返回值403，表示删除的用户不存在

{
  "error": "forbidden_op",
  "timestamp": 1542556235498,
  "duration": 0,
  "exception": "com.easemob.group.exception.ForbiddenOpException",
  "error_description": "users [user10, user2] are not members of this group!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542556279096,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取聊天室管理员列表

获取聊天室管理员列表的接口。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

需要在请求时对应填写{chatroom_id}，需要获取的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息

参数	说明
data	聊天室管理员用户 ID

请求示例

curl -X GET http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示获取聊天室管理员成功

{
    "action": "get",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin",
    "entities": [],
    "data": ["user1"],
    "timestamp": 1489073361210,
    "duration": 0,
    "organization": "easemob-demo",
    "applicationName": "testapp",
    "count": 1
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

添加聊天室管理员

将一个聊天室成员角色提升为聊天室管理员。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

需要在请求时对应填写{chatroom_id}，需要添加管理员的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
newadmin	要添加为聊天室管理员的用户 ID

Response Body

参数	说明
result	操作结果；success：添加成功
newadmin	添加为聊天室管理员的用户 ID

请求示例

curl -X POST http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin -d '{"newadmin":"user1"}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示添加聊天室管理员成功

{
    "action": "post",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin",
    "entities": [],
    "data": {
        "result": "success",
        "newadmin": "user1"
    },
    "timestamp": 1489073130083,
    "duration": 1,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

移除聊天室管理员

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

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}

需要在请求时对应填写{chatroom_id}，要移除管理员的聊天室 ID ，以及{oldadmin}，需要移除的管理员用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin/user1 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示聊天室管理员移除成功

{
    "action": "delete",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/admin/user1",
    "entities": [],
    "data": {
        "result": "success",
        "oldadmin": "user1"
    },
    "timestamp": 1489073432732,
    "duration": 1,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

管理禁言

环信提供多个管理聊天室禁言列表的接口，包括获取、将用户添加、移除禁言列表等

名称	请求	描述
获取禁言列表	/{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},…)	从聊天室的禁言列表中移除用户

添加禁言

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

HTTP Request

	/{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

请求示例

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'

可能返回的结果示例

返回值200，表示添加禁言成功

{
    "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"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

移除禁言

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

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute/{member1}(,{member2},…)

需要在请求时对应填写{chatroom_id}，需要移除禁言的聊天室 ID ，以及{member1}(,{member2},…，需要移除禁言的用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE HTTP://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/mute/user1  -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示移除禁言成功

{
    "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"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取禁言列表

获取当前聊天室的禁言用户列表。

HTTP Request

	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute

需要在请求时对应填写{chatroom_id}，需要获取禁言列表的聊天室 ID 。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

参数	说明
expire	禁言到期的时间戳（从1970年1月1日开始的毫秒数。如果禁言时间传的值为“-1”，那么该时间戳为固定的4638873600000，请参考mute_duration参数的说明）
user	被禁言用户的 ID

请求示例

curl -X GET HTTP://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/mute -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示获取禁言列表成功

{
    "action": "post",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/1265710621211/mute",
    "entities": [],
    "data": [{
        "expire": 1489158589481,
        "user": "user1"
    },
    {
        "expire": 1489158589481,
        "user": "user2"
    }],
    "timestamp": 1489072802179,
    "duration": 0,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 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

	/{org_name}/{app_name}/chatrooms/super_admin

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

参数	说明
data	聊天室超级管理员ID列表

请求示例

curl -X GET http://a1.easemob.com/easemob-demo/testapp/chatrooms/super_admin?pagenum=2&pagesize=2 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

可能返回的结果示例

返回值200，表示获取聊天室成员成功

{
    "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
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

添加超级管理员

给用户添加聊天室超级管理员身份。

HTTP Request

	/{org_name}/{app_name}/chatrooms/super_admin

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
superadmin	添加的用户名称

Response Body

在返回值中查看data字段包含的信息

参数	说明
result	添加结果，true表示添加成功，false表示添加失败

请求示例

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"}'

可能返回的结果示例

返回值200，表示聊天室成员添加成功

{
    "action": "post",
    "application": "9fa492a0-40b1-11e5-b1b9-a76b05da6904",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/hxdemo2/chatrooms/super_admin",
    "entities": [],
    "data": {
        "result": "success",
        "resource": ""
    },
    "timestamp": 1596187658017,
    "duration": 1,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

返回值404，表示添加的用户或聊天室不存在

{
  "error": "resource_not_found",
  "timestamp": 1542554114398,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542554229364,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

移除超级管理员

移除超级管理员。

HTTP Request

	/{org_name}/{app_name}/chatrooms/super_admin/{superAdmin}

需要在请求时对应填写{superAdmin}，需要删除的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/chatrooms/super_admin/user1'

可能返回的结果示例

返回值200，表示聊天室成员删除成功

{
    "action": "delete",
    "application": "9fa492a0-40b1-11e5-b1b9-a76b05da6904",
    "uri": "http://a1.easemob.com/easemob-demo/testapp/chatrooms/super_admin/hxtest10",
    "entities": [],
    "data": {
        "newSuperAdmin": "user1",
        "resource": ""
    },
    "timestamp": 1596187855832,
    "duration": 0,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "group_authorization",
  "timestamp": 1542555910183,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

上一页：群组管理

下一页：聊天记录

目录

聊天室管理

聊天室数据结构

聊天室角色

REST API 在线测试说明

管理聊天室

获取 APP 中所有的聊天室

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

获取用户加入的聊天室

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

获取聊天室详情

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

创建聊天室

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

修改聊天室信息

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

删除聊天室

HTTP Request

Request Headers

请求示例

可能返回的结果示例

管理聊天室成员

分页获取聊天室成员

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

添加单个聊天室成员

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

批量添加聊天室成员

HTTP Request

Request Headers

Request Body

Response Body

请求示例

可能返回的结果示例

删除单个聊天室成员

HTTP Request

Request Headers

请求示例

可能返回的结果示例

批量删除聊天室成员

HTTP Request

Request Headers

请求示例

可能返回的结果示例

获取聊天室管理员列表

HTTP Request

Request Headers

Response Body

请求示例

可能返回的结果示例

添加聊天室管理员