目录

聊天室管理

更新时间: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)、普通聊天室成员之外,新增聊天室管理员角色。

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


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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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-Typeapplication/json
AuthorizationBearer ${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 在线测试


上一页:群组管理

下一页:聊天记录