群组管理


环信提供了 REST API 来管理 APP 中的群组。

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

群组数据结构

字段名 类型 描述
id String 群组 ID,群组唯一标识符,由环信服务器生成,等同于单个用户的环信 ID。
name String 群组名称,根据用户输入创建,字符串类型。
description String 群组描述,根据用户输入创建,字符串类型。
public Boolean 群组类型:true:公开群,false:私有群。
membersonly Boolean 加入群组是否需要群主或者群管理员审批。true:是,false:否。
allowinvites Boolean 是否允许群成员邀请别人加入此群。 true:允许群成员邀请人加入此群,false:只有群主才可以往群里加人。
maxusers Integer 群成员上限,创建群组的时候设置,可修改。
affiliations_count Integer 现有成员总数。
affiliations Array 现有成员列表,包含了 owner 和 member。例如:“affiliations”:[{“owner”: “13800138001”},{“member”:“v3y0kf9arx”},{“member”:“xc6xrnbzci”}]。
owner String 群主的环信 ID。例如:{“owner”: “13800138001”}。
member String 群成员的环信 ID。例如:{“member”:“xc6xrnbzci”}。
invite_need_confirmBoolean邀请加群,被邀请人是否需要确认。如果是true,表示邀请加群需要被邀请人确认;如果是false,表示不需要被邀请人确认,直接将被邀请人加入群。 该字段的默认值为true。

群组角色

群组除了群主、普通群成员之外,新增群管理员角色。

群组角色权限范围:群主 > 群管理员 > 普通群成员

  • 群主拥有群的所有权限;
  • 群管理员拥有管理黑名单、禁言等权限。

管理群组

分页获取 APP 下的群组

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

  • Path: /{org_name}/{app_name}/chatgroups
  • HTTP Method: GET
  • URL Params: limit 预期获取的记录数,数字类型; cursor 游标,如果数据还有下一页,API 返回值会包含此字段,字符类型。
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body:
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:404(此群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

第一页

curl 示例:

curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups?limit=2"

Response 示例:

{
    "action": "get",
    "params": {
        "limit": [
            "2"
        ]
    },
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups",
    "entities": [],
    "data": [
        {
            "owner": "easemob-demo#chatdemoui_user001",
            "groupid": "100743775617286960",
            "affiliations": 2,
            "type": "group",
            "last_modified": "1441021038124",
            "groupname": "user001g"
        },
        {
            "owner": "easemob-demo#chatdemoui_hxt004",
            "groupid": "100973270123152176",
            "affiliations": 1,
            "type": "group",
            "last_modified": "1441074471486",
            "groupname": "hxt004ht"
        }
    ],
    "timestamp": 1441094193812,
    "duration": 14,
    "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z",
    "count": 2
}

第二页

curl 示例:

curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LAAA" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups?limit=10&cursor=Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z"

Response 示例:

{
    "action": "get",
    "params": {
        "cursor": [
            "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z"
        ],
        "limit": [
            "2"
        ]
    },
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups",
    "entities": [],
    "data": [
        {
            "owner": "easemob-demo#chatdemoui_jianxin1",
            "groupid": "1432966654513221",
            "affiliations": 3,
            "type": "group",
            "last_modified": "1438605276924",
            "groupname": "testrestgrp12"
        },
        {
            "owner": "easemob-demo#chatdemoui_jianxin1",
            "groupid": "1432966654926530",
            "affiliations": 3,
            "type": "group",
            "last_modified": "1432966654927",
            "groupname": "testrestgrp11"
        }
    ],
    "timestamp": 1441094237757,
    "duration": 580,
    "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV81",
    "count": 2
}

获取一个用户参与的所有群组

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

  • Path: /{org_name}/{app_name}/users/{username}/joined_chatgroups
  • HTTP Method: GET
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略
  • 可能的错误码:404(此用户不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X GET 'https://a1.easemob.com/easemob-demo/chatdemoui/users/kenshinn/joined_chatgroups' -H 'Authorization: Bearer YWMtF4ZxXlLmEeS7kWnCMObSnQAAAUo-7HZU-bP7-SJzYGCaUdumxsGelt8pmss'

Response 示例:

{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/kenshinn/joined_chatgroups",
  "entities" : [ ],
  "data" : [ {
    "groupid" : "1413193977786197",
    "groupname" : "kenshingrou"
  }, {
    "groupid" : "1413194058403881",
    "groupname" : "kenshinngr1"
  }, {
    "groupid" : "1413601924284",
    "groupname" : "kenshinngroup002"
  }, {
    "groupid" : "1413026100974",
    "groupname" : "18192976732 的地图"
  }, {
    "groupid" : "141327925742855",
    "groupname" : "kenshinngro"
  }, {
    "groupid" : "1413211974686981",
    "groupname" : "5cxhactgdjgr"
  } ],
  "timestamp" : 1413428676499,
  "duration" : 80
}

获取群组详情

可以获取一个或多个群组的详情。当获取多个群组的详情时,会返回所有存在的群组的详情,对于不存在的群组,response body内返回“group id doesn't exist”。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id1},{group_id2}
  • HTTP Method: GET
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:404(此群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE"  -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1410511142870,1408518613503"

Response 示例:

{
  "action" : "get",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1410511142870,1408518613503",
  "entities" : [ ],
  "data" : [ {
    "id" : "1408518613503",
    "name" : "Jay13800138000",
    "description" : "",
    "public" : false,
    "membersonly" : true,
    "allowinvites" : false,
    "maxusers" : 200,
    "affiliations_count" : 3,
    "affiliations" : [ {
      "owner" : "13800138001"
     }, {
      "member" : "v3y0kf9arx"
     }, {
      "member" : "xc6xrnbzci"
     } ]
   }, {
    "id" : "1410511142870",
    "name" : "abc",
    "description" : "",
    "public" : false,
    "membersonly" : true,
    "allowinvites" : false,
    "maxusers" : 200,
    "affiliations_count" : 1,
    "affiliations" : [ {
      "owner" : "u366"
    } ]
  } ],
  "timestamp" : 1411526263806,
  "duration" : 34,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

创建一个群组

创建一个群组,并设置群组名称、群组描述、公开群/私有群属性、群成员最大人数(包括群主)、加入公开群是否需要批准、群主、以及群成员。

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

  • Path: /{org_name}/{app_name}/chatgroups
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body:
{
    "groupname":"testrestgrp12", //群组名称,此属性为必须的
    "desc":"server create group", //群组描述,此属性为必须的
    "public":true, //是否是公开群,此属性为必须的
    "maxusers":300, //群组成员最大数(包括群主),值为数值类型,默认值200,最大值2000,此属性为可选的
    "members_only":true // 加入群是否需要群主或者群管理员审批,默认是false
    "allowinvites": true  //是否允许群成员邀请别人加入此群。 true:允许群成员邀请人加入此群,false:只有群主或者管理员才可以往群里加人。
    "owner":"jma1", //群组的管理员,此属性为必须的
    "members":["jma2","jma3"] //群组成员,此属性为可选的,但是如果加了此项,数组元素至少一个(注:群主jma1不需要写入到members里面)
}
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(owner不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X POST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw45TXUWSIrXI8' -d '{"groupname":"testrestgrp12","desc":"server create group","public":true,"approval":true,"owner":"2ewcgkhhxf","maxusers":300,"members":["zh9w1hc49q"]}'

Response 示例:

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "groupid" : "1411527886490154"
  },
  "timestamp" : 1411527886457,
  "duration" : 125,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

修改群组信息

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

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}
  • HTTP Method: PUT
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body:
{
    "groupname":"test rest group", //群组名称,修改时值不能包含斜杠("/")。
    "description":"update group info", //群组描述,修改时值不能包含斜杠("/")。
    "maxusers":300 //群组成员最大数(包括群主),值为数值类型
}
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X PUT 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1412957434136' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIrXI8' -d '{"groupname":"testrestgrp12","description":"update groupinfo","maxusers":400}'

Response 示例:

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

删除群组

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X DELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411527886490154' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw45TXUWSIrXI8'

Response 示例:

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

管理群组成员

分页获取群组成员

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/users
  • HTTP Method: GET
  • URL Params: pagenum:页码,从1开始;pagesize: 每页显示数量,最大不超过1000
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/users",
	  "entities": [],
	  "data": [
	    {
	      "member": "user1"
	    },
	    {
	      "member": "user2"
	    }
	  ],
	  "timestamp": 1489074511416,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui",
	  "count": 2
	}

添加群组成员[单个]

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

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/{username}
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略
  • 可能的错误码:400(被添加的IM用户不存在)、403(IM用户已经是群成员)、404(此群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X POST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users/q4xpsfjfvf' -H 'Authorization: Bearer YWMtgNIiTFAwEeSB9olyTIXFtwAAAUotKvWaUOaUuqeuhNMgOgozO4popVZe-Ls'

Response 示例:

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "action" : "add_member",
    "result" : true,
    "groupid" : "1411816013089",
    "user" : "q4xpsfjfvf"
  },
  "timestamp" : 1413012512005,
  "duration" : 29,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

添加群组成员[批量]

为群组添加多个成员,一次最多可以添加60位成员。如果所有用户均已是群成员,将添加失败,并返回错误。

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

  • Path: /{org_name}/{app_name}/chatgroups/{chatgroupid}/users
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: {“usernames”:[“username1”,”username2”]}’ — usernames 固定属性,作为 JSON 的 KEY;username1/username2 要添加到群中的成员用户名,可变
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略
  • 可能的错误码:400(用户不存在)、403(所有用户均已是群成员)、404(群组id不存在、添加owner为member)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X  POST -H 'Authorization: Bearer YWMtF4ZxXlLmEeS7kWnCMObSnQAAAUo-7HZU-bP7-SJzYGCaUdumxsGelt8pmE4' -i  'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users' -d '{"usernames":["5cxhactgdj","mh2kbjyop1"]}'

Response 示例:

{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "newmembers" : [ "5cxhactgdj", "mh2kbjyop1" ],
    "action" : "add_member",
    "groupid" : "1411816013089"
  },
  "timestamp" : 1413428995083,
  "duration" : 4,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

移除群组成员[单个]

从群中移除某个成员。如果被移除用户不是群成员,将移除失败,并返回错误。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/{username}
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略
  • 可能的错误码:403(被移除用户不在群组里等)、404(被移除的IM用户不存在,此群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X DELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1411816013089/users/q4xpsfjfvf' -H 'Authorization: Bearer YWMtgNIiTFAwEeSB9olyTIXFtwAAAUotKvWaUOaUuqeuhNMgOgozO4popVZe-Ls'

Response 示例:

{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : {
    "action" : "remove_member",
    "result" : true,
    "groupid" : "1411816013089",
    "user" : "q4xpsfjfvf"
  },
  "timestamp" : 1413012566573,
  "duration" : 56,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}

移除群组成员[批量]

移除群成员,用户名之间用英文逗号分隔。如果所有被移除用户均不是群成员,将移除失败,并返回错误。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/users/memeber1,member2,member3
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Content-Type”:“application/json”,“Authorization”:“Bearer ${token}”}
  • Request Body: 无
  • Response Body: result 为 true 表示移除成功;result 为 false 表示移除失败,此时 reason 字段注明失败原因。
  • 可能的错误码:403(被移除用户不在群组里等)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X DELETE -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1433495614983/users/user1,user2,user3"

Response 示例:

{
            "action": "delete",
            "application": "9b848cf0-fafe-11e4-b5b8-0f74e8e740f7",
            "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
            "entities": [],
            "data": [
                {
                    "result": false,
                    "action": "remove_member",
                    "reason": "user ttestuser0015981 doesn't exist.",
                    "user": "user1",
                    "groupid": "1433492852257879"
                },
                {
                    "result": true,
                    "action": "remove_member",
                    "user": "user2",
                    "groupid": "1433492852257879"
                },
                {
                    "result": true,
                    "action": "remove_member",
                    "user": "user3",
                    "groupid": "1433492852257879"
                }
            ],
            "timestamp": 1433492935318,
            "duration": 84,
            "organization": "easemob-demo",
            "applicationName": "chatdemoui"
} 

获取群管理员列表

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin
  • HTTP Method: GET
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/admin",
	  "entities": [],
	  "data": [
	    "z1"
	  ],
	  "timestamp": 1489073361210,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui",
	  "count": 1
	}

添加群管理员

将一个群成员角色提升为群管理员。

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 参见curl示例
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XPOST HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/admin",
	  "entities": [],
	  "data": {
	    "result": "success",
	    "newadmin": "z1"
	  },
	  "timestamp": 1489073130083,
	  "duration": 1,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}

移除群管理员

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin}
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XDELETE HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/admin/z1",
	  "entities": [],
	  "data": {
	    "result": "success",
	    "oldadmin": "z1"
	  },
	  "timestamp": 1489073432732,
	  "duration": 1,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}

转让群组

修改群组 Owner 为同一群组中的其他成员。

注意:将群组Owner转让给其他群成员后,原群组Owner将变成群成员。

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

  • Path: /{org_name}/{app_name}/chatgroups/{groupid}
  • HTTP Method: PUT
  • URL Params: 无
  • Request Headers: {“Content-Type”:“application/json”,“Authorization”:“Bearer ${token}”}
  • Request Body: {“newowner”:“${new_owner_user}”}
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -X PUT -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/1433495614983" -d '{"newowner":"username1"}'

Response 示例:

{
        "action": "put",
        "application": "9b848cf0-fafe-11e4-b5b8-0f74e8e740f7",
        "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
        "entities": [],
        "data": {
            "newowner": true
        },
        "timestamp": 1433495614983,
        "duration": 194,
        "organization": "easemob-demo",
        "applicationName": "chatdemoui"
}

管理黑名单

查询群组黑名单

查询一个群组黑名单中的用户列表。位于黑名单中的用户查看不到该群组的信息,也无法收到该群组的消息。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
  • HTTP Method: GET
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 参见“curl 示例”
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XGET 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response 示例:

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users",
  "entities": [],
  "data": [
    "hxt001",
    "hxt002",
    "hxt003",
    "hxt004"
  ],
  "timestamp": 1439557362316,
  "duration": 4
}

添加用户至群组黑名单[单个]

添加一个用户进入一个群组的黑名单。群主无法被加入群组的黑名单。

用户进入群组黑名单后,会收到消息:You are kicked out of the group xxx。之后,该用户查看不到该群组的信息,也收不到该群组的消息。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 参见curl示例
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XPOST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt002' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response 示例:

{
  "action": "post",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_blocks",
    "user": "hxt002",
    "groupid": "91340342439182920"
  },
  "timestamp": 1439557079351,
  "duration": 34,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}

添加用户至群组黑名单[批量]

添加多个用户进入一个群组的黑名单,一次性最多可以添加60个用户。群主无法被加入群组的黑名单。

用户进入群组黑名单后,会收到消息:You are kicked out of the group xxx。之后,该用户查看不到该群组的信息,也收不到该群组的消息。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: {“usernames”:[“username1”,“username2”,“username3”]}
  • Response Body: result为true表示添加成功;result为false表示添加失败,此时reason字段注明失败原因。
  • 可能的错误码:404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XPOST 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1' -d '{"usernames":["hxt001","hxt002","hxt003"]}'

Response 示例:

{
  "action": "post",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "add_blocks",
      "reason": "the user hxt001 doesn't exist",
      "user": "hxt001",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "add_blocks",
      "user": "hxt002",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "add_blocks",
      "user": "hxt003",
      "groupid": "91340342439182920"
    }
  ],
  "timestamp": 1439557269929,
  "duration": 190,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}

从群组黑名单移除用户[单个]

从群组黑名单中移除一个用户。对于群组黑名单中的用户,如果需要将其再次加入群组,需要先将其从群组黑名单中移除。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username}
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的json数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XDELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt001' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response 示例:

{
  "action": "delete",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_blocks",
    "user": "hxt001",
    "groupid": "91340342439182920"
  },
  "timestamp": 1439557411653,
  "duration": 13,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}

从群组黑名单移除用户[批量]

从群组黑名单中移除多个用户。对于群组黑名单中的用户,如果需要将其再次加入群组,需要先将其从群组黑名单中移除。

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username1},{username2}
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: result为true表示移除成功;result为false表示移除失败,此时reason字段注明失败原因。
  • 可能的错误码:401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl 示例:

curl -XDELETE 'https://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/91340342439182920/blocks/users/hxt001,hxt002,hxt003' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Response 示例:

{
  "action": "delete",
  "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt001",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt002",
      "groupid": "91340342439182920"
    },
    {
      "result": true,
      "action": "remove_blocks",
      "user": "hxt003",
      "groupid": "91340342439182920"
    }
  ],
  "timestamp": 1439557455684,
  "duration": 23,
  "organization": "easemob-demo",
  "applicationName": "chatdemoui"
}

管理禁言

添加禁言

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute
  • HTTP Method: POST
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 参见curl示例
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XPOST HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/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时间戳。

移除禁言

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

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute/{member1}(,{member2},…)
  • HTTP Method: DELETE
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XDELETE HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/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"
	}

获取禁言列表

获取当前群组的禁言用户列表。

  • Path: /{org_name}/{app_name}/chatgroups/{group_id}/mute
  • HTTP Method: GET
  • URL Params: 无
  • Request Headers: {“Authorization”:”Bearer ${token}”}
  • Request Body: 无
  • Response Body: 详情参见示例返回值,返回的 JSON 数据中会包含除上述属性之外的一些其他信息,均可以忽略。
  • 可能的错误码:400(用户不存在)、404(群组id不存在)、401(未授权[无token、token错误、token过期])、5xx。详见:服务器端 REST API 常见错误码

curl示例:

curl -XGET HTTP://a1.easemob.com/easemob-demo/chatdemoui/chatgroups/10130212061185/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/chatgroups/10130212061185/mute",
	  "entities": [],
	  "data": [
	    {
	      "expire": 1489158589481,
	      "user": "z3"
	    },
	    {
	      "expire": 1489158589481,
	      "user": "z1"
	    },
	    {
	      "expire": 1489158589481,
	      "user": "z2"
	    }
	  ],
	  "timestamp": 1489072802179,
	  "duration": 0,
	  "organization": "easemob-demo",
	  "applicationName": "chatdemoui"
	}

上一页:发送消息

下一页:聊天室管理