目录

聊天室管理


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

单个APP创建聊天室数量有限制,如需增加可根据具体业务联系商务解决。单用户ID只能加入500个聊天室。

聊天室数据结构

名称 类型 描述
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)、普通聊天室成员之外,新增聊天室管理员角色。

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

管理聊天室

获取 APP 中所有的聊天室

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X GET -H "Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIrXI8" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms?pagenum=2&pagesize=3"

Response 示例:

{
  "action": "get",
  "params": {
    "pagesize": [
      "3"
    ],
    "pagenum": [
      "2"
    ]
  },
  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatrooms",
  "entities": [],
  "data": [
    {
      "id": "124375842267595332",
      "name": "testchatroom",
      "owner": "zp300",
      "affiliations_count": 631
    },
    {
      "id": "124375913398796852",
      "name": "azpp",
      "owner": "zp300",
      "affiliations_count": 532
    },
    {
      "id": "132598658687304132",
      "name": "123456",
      "owner": "55",
      "affiliations_count": 435
    }
  ],
  "timestamp": 1477543557486,
  "duration": 21,
  "count": 3
}

获取用户加入的聊天室

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X GET 'https://a1.easemob.com/easemob-demo/chatdemoui/users/jma1/joined_chatrooms' -H 'Authorization: Bearer YWMtgNIiTFAwEeSB9olyTIXFtwAAAUotKvWaUOaUuqeuhNMgOgozO4popVZe-Ls'

Response 示例:

{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/jma1/joined_chatrooms",
  "entities" : [ ],
  "data" : [ {
    "id" : "1432266600611977",
    "name" : "testchatroom"
  } ],
  "timestamp" : 1432268305229,
  "duration" : 23
}

获取聊天室详情

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X GET -H "Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw45TXUWSIrXI8"  -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1432259621444159"

Response 示例:

{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1432259621444159",
  "entities" : [ ],
  "data" : [ {
    "membersonly" : false,
    "allowinvites" : false,
    "public" : true,
    "name" : "hxt001room0516",
    "description" : "chatroom description",
    "affiliations" : [ {
      "owner" : "hxt001"
    } ],
    "id" : "1432259621444159",
    "maxusers" : 2000,
    "affiliations_count" : 1
  } ],
  "timestamp" : 1432267287589,
  "duration" : 1
}

创建一个聊天室

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

{
    "name":"testchatroom", //聊天室名称,此属性为必须的
    "description":"server create chatroom", //聊天室描述,此属性为必须的
    "maxusers":300, //聊天室成员最大数(包括聊天室创建者),值为数值类型,默认值200,最大值5000,此属性为可选的
    "owner":"jma1", //聊天室的管理员,此属性为必须的
    "members":["jma2","jma3"] //聊天室成员,此属性为可选的,但是如果加了此项,数组元素至少一个(注:聊天室创建者jma1不需要写入到members里面)
}

curl 示例:

curl -X POST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms' -H 'Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE' -d '{"name":"testchatroom","description":"server create chatroom","owner":"jma1","maxusers":300,"members":["ceshia"]}'

Response 示例:

{
    "action": "post",
    "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "id": "1432289956668375"
    },
    "timestamp": 1432289956589,
    "duration": 85,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

修改聊天室信息

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

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

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

{
    "name":"test chatroom", //聊天室名称,修改时值不能包含斜杠("/")。
    "description":"update chatroom info", //聊天室描述,修改时值不能包含斜杠("/")。
    "maxusers":200, //聊天室成员最大数(包括聊天室创建者),值为数值类型
}

curl 示例:

curl -X PUT 'https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1432259621444159' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnC3U4gI0-rQImw4523fWqIrXI8' -d '{"name":"test chatroom","description":"update chatroominfo","maxusers":200}'

Response 示例:

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

删除聊天室

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

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X DELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1432259621444159' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnaf3sqrQFnCU4gI0-rQImw45TXUWSIrXI8'

Response 示例:

{
    "action": "delete",
    "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "success": true,
        "id": "1432289956668375"
    },
    "timestamp": 1432290072350,
    "duration": 146,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

管理聊天室成员

分页获取聊天室成员

curl 示例;

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

Response示例:

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

添加聊天室成员[单个]

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/96330911796167468/users/jianxin1"

Response 示例:

{
    "action": "post",
    "application": "ca91dcc0-89aa-11e4-8e50-4d99c3a32a95",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "result": true,
        "action": "add_member",
        "id": "96330911796167468",
        "user": "jianxin1"
    },
    "timestamp": 1441094788695,
    "duration": 27,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

添加聊天室成员[批量]

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

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/96330911796167468/users" -d '{"usernames":["jianxin1", "jianxin2"]}'

Response 示例:

{
    "action": "post",
    "application": "ca91dcc0-89aa-11e4-8e50-4d99c3a32a95",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "newmembers": [
            "jianxin1",
            "jianxin2"
        ],
        "action": "add_member",
        "id": "96330911796167468"
    },
    "timestamp": 1441095085904,
    "duration": 18,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

删除聊天室成员[单个]

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

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X DELETE -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/96330911796167468/users/jianxin1"

Response 示例:

{
    "action": "delete",
    "application": "ca91dcc0-89aa-11e4-8e50-4d99c3a32a95",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "result": true,
        "action": "remove_member",
        "id": "96330911796167468",
        "user": "jianxin1"
    },
    "timestamp": 1441095234884,
    "duration": 13,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

删除聊天室成员[批量]

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

注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见接口限流说明

curl 示例:

curl -X DELETE -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/96330911796167468/users/jianxin1,jianxin2"

Response 示例:

{
    "action": "delete",
    "application": "ca91dcc0-89aa-11e4-8e50-4d99c3a32a95",
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": [
        {
            "result": true,
            "action": "remove_member",
            "id": "96330911796167468",
            "user": "jianxin1"
        },
        {
            "result": false,
            "action": "remove_member",
            "reason": "user jianxni2 doesn't exist.",
            "id": "96330911796167468",
            "user": "jianxni2"
        }
    ],
    "timestamp": 1441095321332,
    "duration": 21,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}

获取聊天室管理员列表

curl示例:

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

Response示例:

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

添加聊天室管理员

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

curl示例:

curl -XPOST http://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1265710621211/admin -d '{"newadmin":"z1"}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response示例:

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

移除聊天室管理员

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

curl示例:

curl -XDELETE http://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1265710621211/admin/z1 -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response示例:

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

管理禁言

获取禁言列表

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

curl示例:

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

Response示例:

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

添加禁言

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

curl示例:

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

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

Response示例:

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

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

移除禁言

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

curl示例:

curl -XDELETE HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatrooms/1265710621211/mute/z1,z2,z3  -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response示例:

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