聊天室管理

大约 58 分钟

聊天室管理

本文介绍聊天室管理相关接口,包括添加、获取、修改和删改聊天室以及聊天室成员管理相关操作。

提示

仅聊天室超级管理员具有在客户端创建聊天室的权限。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

聊天室成员角色

成员角色描述管理权限
普通成员不具备管理权限的聊天室成员。普通成员可以修改自己的聊天室信息。
聊天室管理员由聊天室创建者授权,协助聊天室管理,具有管理权限。管理员可以管理聊天室内的普通成员。 最多支持添加 99 个管理员。
聊天室所有者聊天室的创建者,具有聊天室最高权限。聊天室所有者可以指定聊天室管理员、解散聊天室、更改聊天室信息、管理聊天室成员。

公共参数

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息
chatroom_idString聊天室 ID。
usernameString用户 ID。
nameString聊天室名称,最大长度为 128 个字符。
descriptionString聊天室描述,最大长度为 512 个字符。
maxusersInt聊天室成员数上限,创建聊天室时设置。该参数的默认最大值为 10,000,如需调整请联系商务。

响应参数

参数类型描述
actionString请求方法。
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名,与请求参数 host 相同。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString系统内为应用生成的唯一标识,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
idString聊天室 ID,聊天室唯一标识,由环信即时通讯 IM 服务器生成。
entitiesJSON响应实体。
dataJSON数据详情。
uuidString系统内为用户或者应用生成的系统内唯一标识,开发者无需关心。
createdString用户、群组或聊天室的创建时间,Unix 时间戳,单位为毫秒。
usernameString用户 ID。
affiliations_countInt聊天室现有成员总数。
affiliationsArray聊天室现有成员列表,数组类型,包含 ownermember 元素,即聊天室所有者和聊天室成员(包括聊天室管理员)。例如: “affiliations”:[{“owner”: “13800138001”},{“member”:”v3y0kf9arx”},{“member”:”xc6xrnbzci”}]。
ownerString聊天室所有者的用户 ID。例如:{“owner”: “13800138001”}。
memberString聊天室成员的用户 ID,包括聊天室管理员和普通成员的用户 ID。例如:{“member”:”xc6xrnbzci”}。
timestampLongHTTP 响应的 Unix 时间戳,单位为毫秒。
durationLong从发送 HTTP 请求到响应的时长,单位为毫秒。

认证方式

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的鉴权方式,详见 使用 App Token 鉴权

管理超级管理员

在即时通讯应用中,仅聊天室超级管理员具有在客户端创建聊天室的权限。

环信即时通讯 IM 提供多个管理超级管理员的接口,包括获取、添加、移除等操作。

添加超级管理员

添加一个聊天室超级管理员。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/super_admin
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
superadminString添加的超级管理员的用户 ID,每次只能添加一个。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.resultBool是否成功添加聊天室超级管理员:
- true:是;
- false:否。
data.propertiesString预留参数,开发者不用关注。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/chatrooms/super_admin'  \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "superadmin": "user1"
}'
响应示例
{
  "action": "post",
  "application": "09XXXX34",
  "applicationName": "XXXX",
  "data": {
    "result": "success",
    "resource": ""
  },
  "duration": 1,
  "entities": [],
  "organization": "XXXX",
  "timestamp": 1656488117703,
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/super_admin"
}

分页获取超级管理员列表

可以分页获取超级管理员列表的接口。

HTTP 请求

直接获取:

GET https://{host}/{org_name}/{app_name}/chatrooms/super_admin

分页获取:

GET https://{host}/{org_name}/{app_name}/chatrooms/super_admin?pagenum={N}&pagesize={N}
路径参数

参数及描述详见 公共参数

查询参数
参数类型是否必需描述
pagenumInt当前页码,默认值为 1。
pagesizeInt每页返回的超级管理员数量,默认值为 10。
请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataArray超级管理员的用户 ID 列表。
params.pagesizeInt每页返回的超级管理员数量。
params.pagenumInt当前页码。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET https://XXXX/XXXX/XXXX/chatrooms/super_admin?pagenum=2&pagesize=2 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "application": "9fXXXX04",
  "params": {
    "pagesize": ["2"],
    "pagenum": ["2"]
  },
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/super_admin",
  "entities": [],
  "data": ["hXXXX1", "hXXXX11", "hXXXX10"],
  "timestamp": 1596187292391,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 3
}

撤销超级管理员

撤销超级管理员权限,用户将不能再创建聊天室。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/super_admin/{superAdmin}
路径参数
参数类型是否必需描述
superAdminString要撤销超级管理员权限的用户 ID。

其他参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.newSuperAdminString被撤销超级管理员权限的用户 ID。
data.resourceString预留参数,开发者不用关注。
propertiesString预留参数,开发者不用关注。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl --location --request DELETE 'https://XXXX/XXXX/XXXX/chatrooms/super_admin/XXXX'
--header 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "application": "09XXXX34",
  "applicationName": "XXXX",
  "data": {
    "newSuperAdmin": "XXXX",
    "resource": ""
  },
  "duration": 0,
  "entities": [],
  "organization": "XXXX",
  "properties": {},
  "timestamp": 1656488154100,
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/super_admin/XXXX"
}

管理聊天室

环信即时通讯 IM 提供多个接口实现聊天室管理,包括对聊天室的创建、获取、修改、移除等管理功能。

获取 app 中的聊天室

分页获取应用下的聊天室列表和信息。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms?limit={N}&cursor={cursor}
路径参数

参数及描述详见 公共参数

查询参数
参数类型是否必需描述
limitInt每次期望返回的聊天室数量。取值范围为 [1,100],默认值为 10。该参数仅在分页获取时为必需。
cursorString数据查询的起始位置。该参数仅在分页获取时为必需。

提示

若请求中均未设置 limitcursor,环信服务器返回聊天室列表的第一页中前 10 个聊天室。

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.idString聊天室 ID,聊天室唯一标识,由环信即时通讯 IM 服务器生成。
data.nameString聊天室名称。
data.ownerString聊天室创建者的用户 ID。例如:{“owner”: “user1”}。
data.affiliations_countInt聊天室现有成员总数(包含聊天室创建者)。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl --location --request GET 'https://XXXX/XXXX/XXXX/chatrooms?limit=10' \
--header 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "data": {
    "id": "662XXXX13",
    "name": "testchatroom1",
    "owner": "user1",
    "affiliations_count": 2
  }
}

获取用户加入的聊天室

根据用户 ID 分页获取该用户加入的聊天室。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{username}/joined_chatrooms?pagenum={N}&pagesize={N}
路径参数

参数及描述详见 公共参数

查询参数
参数类型是否必需描述
pagenumInt当前页码,默认值为 1。
pagesizeInt每页返回的聊天室数量,取值范围为 [1,1000],默认值为 1000

提示

若查询参数 pagenumpagesize 均不传,服务器返回用户最新加入的 500 个聊天室。

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array聊天室详情。
- idString聊天室 ID,聊天室唯一标识,由环信即时通讯 IM 服务器生成。
- nameString聊天室名称,最大长度为 128 字符。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/joined_chatrooms?pagenum=1&pagesize=10'
响应示例
{
    "action": "get",
    "application": "48472d89-5846-XXXX-XXXX-5fa4b79af9b1",
    "applicationName": "XXXX",
    "count": 2,
    "data": [
        {
            "id": "216295074234369",
            "name": "fd",
            "disabled": "false"
        },
        {
            "id": "216294461865985",
            "name": "testChatRoom",
            "disabled": "false"
        }
    ],
    "duration": 0,
    "entities": [],
    "organization": "XXXX",
    "params": {
        "pagesize": [
            "10"
        ],
        "pagenum": [
            "1"
        ]
    },
    "properties": {},
    "timestamp": 1685673568976,
    "uri": "http://XXXX/XXXX/XXXX/users/user2/joined_chatrooms"
}

查询聊天室详情

查询一个或多个聊天室的详情。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}
路径参数
参数类型是否必需描述
chatroom_idString聊天室 ID,即时通讯服务分配给每个聊天室的唯一标识符,从获取 app 中的聊天室 的响应 body 中获取。
每次最多可查询 100 个聊天室,聊天室 ID 之间用英文逗号(",")分隔,逗号在 URL 中转义为 "%2C"。

其他参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.idString聊天室 ID,聊天室唯一标识符,由环信即时通讯 IM 服务器生成。
data.nameString聊天室名称。
data.descriptionString聊天室描述。
data.membersonlyBool加入聊天室是否需要聊天室所有者或者聊天室管理员审批:
- true:是。
- false:否。
data.allowinvitesBool是否允许聊天室成员邀请其他用户加入该聊天室:
- true:允许聊天室成员邀请他人加入该聊天室。
- false:仅聊天室所有者和管理员可邀请他人加入该聊天室。
data.maxusersInt聊天室成员数上限,创建聊天室时设置。
data.ownerString聊天室所有者的用户 ID。例如:{“owner”: “user1”}。
data.createdLong创建聊天室时间,Unix 时间戳,单位为毫秒。
data.customString聊天室扩展信息。
data.affiliations_countInt现有聊天室成员总数。
data.affiliationsArray现有聊天室成员列表,包含聊天室所有者和成员(包括聊天室管理员)。例如:“affiliations”:[{“owner”: “user1”},{“member”:”user2”},{“member”:”user3”}]。
data.publicBool预留字段,无需关注。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/662XXXX13'
响应示例
{
  "data": {
    "id": "662XXXX13",
    "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
  }
}

创建聊天室

创建一个聊天室,需设置聊天室名称、聊天室描述、聊天室成员最大人数(包括管理员)、聊天室管理员和普通成员以及聊天室扩展信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
nameString聊天室名称,最大长度为 128 个字符。
descriptionString聊天室描述,最大长度为 512 个字符。
maxusersInt聊天室最大成员数(包括聊天室所有者)。取值范围为 [1,10,000],默认值为 1000。如需调整请联系商务。
ownerString聊天室所有者。
membersArray聊天室普通成员和管理员的用户 ID 数组,不包含聊天室所有者的用户 ID。该数组可包含的元素数量不超过 maxusers 的值。若传该参数,确保至少设置一个数组元素。
customString聊天室扩展信息,例如可以给聊天室添加业务相关的标记,不要超过 1,024 个字符。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.idString创建的聊天室的 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "name": "testchatroom1",
   "description": "test",
   "maxusers": 300,
   "owner": "user1",
   "members": [
     "user2"
   ]
 }' 'https://XXXX/XXXX/XXXX/chatrooms'
响应示例
{
  "data": {
    "id": "66XXXX33"
  }
}

修改聊天室信息

修改指定聊天室的信息。仅支持修改聊天室名称、聊天室描述和聊天室最大成员数。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

你只能修改聊天室名称、聊天室描述和聊天室最大成员数。

参数类型是否必需描述
nameString聊天室名称,不能超过 128 个字符。
descriptionString聊天室描述,不能超过 512 个字符。
maxusersInt聊天室最大成员数(包括聊天室所有者),默认可设置的最大人数为 10,000,如需调整请联系商务。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.groupnameBool聊天室名称是否修改成功。
- true:是。
false:否。
data.descriptionBool聊天室描述是否修改成功。
- true:是。
false:否。
data.maxusersBool聊天室最大成员数(包括聊天室所有者)是否修改成功。
- true:是。
false:否。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "name": "testchatroom",
   "description": "test",
   "maxusers": 300
 }' 'https://XXXX/XXXX/XXXX/chatrooms/662XXXX13'
响应示例
{
  "data": {
    "description": true,
    "maxusers": true,
    "groupname": true
  }
}

删除聊天室

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数及描述详见 公共参数

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
data.successBool是否成功删除聊天室:
- true:是;
- false:否。
data.idString删除的聊天室的 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/662XXXX13'
响应示例
{
  "action": "delete",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/662XXXX13",
  "entities": [],
  "data": {
    "success": true,
    "id": "662XXXX13"
  },
  "timestamp": 1542545100474,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

获取聊天室公告

获取指定聊天室 ID 的聊天室公告。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/announcement
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

在返回值中查看 data 字段包含的信息,获取到的聊天室公告信息。

参数类型描述
data.announcementString聊天室公告内容。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/announcement'
响应示例
{
  "action": "get",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/announcement",
  "entities": [],
  "data": {
    "announcement": "XXXX."
  },
  "timestamp": 1542363546590,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

修改聊天室公告

修改指定聊天室 ID 的聊天室公告。聊天室公告内容不能超过 512 个字符。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/announcement
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
字段类型是否必需描述
announcementString修改后的聊天室公告。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.idString聊天室 ID。
data.resultBool是否成功修改聊天室公告:
- true:是;
- false:否。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/announcement' -d '{"announcement" : "聊天室公告…"}'
响应示例
{
  "action": "post",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/announcement",
  "entities": [],
  "data": {
    "id": "12XXXX11",
    "result": true
  },
  "timestamp": 1594808604236,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

设置聊天室自定义属性

指定用户设置特定聊天室的自定义属性。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
metaDataJSON聊天室的自定义属性,存储为键值对(key-value)集合,即 Map<String,String>。该集合中最多可包含 10 个键值对,在每个键值对中,key 为属性名称,最多可包含 128 个字符;value 为属性值,不能超过 4096 个字符。每个聊天室最多可有 100 个自定义属性,每个应用的聊天室自定义属性总大小为 10 GB。
key 支持以下字符集:
• 26 个小写英文字母 a-z;
• 26 个大写英文字母 A-Z;
• 10 个数字 0-9;
• “_”, “-”, “.”。
autoDeleteString当前成员退出聊天室时是否自动删除该自定义属性。
• (默认)'DELETE':是;
• 'NO_DELETE':否。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.successKeysArray设置成功的聊天室属性名称列表。
data.errorKeysObject设置失败的聊天室属性,返回键值对格式,key 为属性名称,value 为失败原因。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "metaData": {
  			"key1": "value1",
				"key2": "value2"
    },
    "autoDelete": "DELETE"
 }' 'https://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1'
响应示例
{
  "data": {
    "successKeys": ["key1"],
    "errorKeys": { "key2": "errorDesc" }
  }
}

获取聊天室自定义属性

获取指定聊天室的自定义属性信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
keysArray聊天室自定义属性名称列表。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataObject聊天室自定义属性,为键值对格式,key 为属性名称,value 为属性值。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "keys": ["key1","key2"]
 }' 'https://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13'
响应示例
{
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

删除聊天室自定义属性

用户删除其设置的聊天室自定义属性。该方法只能删除当前用户设置的聊天室自定义属性,不能删除其他成员设置的自定义属性。

该方法每次最多可删除 10 个自定义属性。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
keysArray聊天室自定义属性名称列表。每次最多可传 10 个自定义属性名称。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.successKeysArray成功删除的聊天室属性名称列表。
data.errorKeysObject删除失败的聊天室属性。这里返回键值对,key 为属性名称,value 为失败原因。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

DELETE -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "keys": ["key1","key2"]
 }' 'https://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1'
响应示例
{
  "data": {
    "successKeys": ["key1"],
    "errorKeys": { "key2": "errorDesc" }
  }
}

强制设置聊天室自定义属性

用户强制设置指定聊天室的自定义属性信息,即该方法可覆盖其他用户设置的聊天室自定义属性。

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
metaDataJSON聊天室的自定义属性,存储为键值对(key-value pair)集合,即 Map<String,String>。该集合中最多可包含 10 个键值对,在每个键值对中,key 为属性名称,最多可包含 128 个字符;value 为属性值,不能超过 4096 个字符。每个聊天室最多可有 100 个自定义属性,每个应用的聊天室自定义属性总大小为 10 GB。
key 支持以下字符集:
• 26 个小写英文字母 a-z;
• 26 个大写英文字母 A-Z;
• 10 个数字 0-9;
• “_”, “-”, “.”。
autoDeleteString当前成员退出聊天室时是否自动删除该自定义属性。
• (默认)'DELETE':是;
• 'NO_DELETE':否。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.successKeysArray设置成功的聊天室属性名称列表。
data.errorKeysObject设置失败的聊天室属性。这里返回键值对,key 为属性名称,value 为失败原因。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "metaData": {
        "key1": "value1",
		"key2": "value2"
    },
    "autoDelete": "DELETE"
 }' 'https://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'
响应示例
{
  "data": {
    "successKeys": ["key1"],
    "errorKeys": { "key2": "errorDesc" }
  }
}

强制删除聊天室自定义属性

用户强制删除聊天室的自定义属性信息,即该方法除了会删除当前用户设置的聊天室自定义属性,还可以删除其他用户设置的自定义属性。

该方法每次最多可删除 10 个自定义属性。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
keysArray聊天室自定义属性的名称列表。每次最多可传 10 个自定义属性名称。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.successKeysArray成功删除的聊天室属性名称列表。
data.errorKeysObject删除失败的聊天室属性。这里返回键值对,key 为属性名称,value 为失败原因。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl  -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "keys": ["key1","key2"]
 }' 'https://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'
响应示例
{
  "data": {
    "successKeys": ["key1"],
    "errorKeys": { "key2": "errorDesc" }
  }
}

管理聊天室成员

环信即时通讯 IM 提供多个接口实现聊天室成员管理,包括添加和移除聊天室成员、转让聊天室所有权以及聊天室黑名单、白名单和禁言列表相关操作。

分页获取聊天室成员列表

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/users?pagenum={N}&pagesize={N}
路径参数

参数及描述详见 公共参数

查询参数
参数类型是否必需描述
pagenumInt查询页码。默认值为 1。
pagesizeInt每页显示的聊天室成员数量。默认值为 1000。取值范围为 [0,1000]。
请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
dataJSON Array聊天室成员信息。
- ownerString聊天室所有者的用户 ID。例如:{“owner”: “user1”}。
- memberString普通聊天室成员或聊天室管理员的用户 ID。例如:{“member”:“user2”}。
countNumber本次调用获取的聊天室成员数量。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/users?pagenum=2&pagesize=2 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "application": "52XXXXf0",
  "params": {
    "pagesize": ["2"],
    "pagenum": ["2"]
  },
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/users",
  "entities": [],
  "data": [
    {
      "owner": "user1"
    },
    {
      "member": "user2"
    }
  ],
  "timestamp": 1489074511416,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 2
}

添加单个聊天室成员

向聊天室添加一个成员。如果待添加的用户在 app 中不存在或已经在聊天室中,则请求失败并返回错误码 400。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
data.resultBool是否添加成功:
- true:是;
- false:否。
data.actionString执行的操作,add_member 表示向聊天室添加成员。
data.idString聊天室 ID,聊天室唯一标识符,由环信即时通讯 IM 服务器生成。
data.userString添加到聊天室的用户。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1'
响应示例
{
  "action": "post",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_member",
    "id": "66XXXX33",
    "user": "user1"
  },
  "timestamp": 1542554038353,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

批量添加聊天室成员

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
usernamesArray添加的用户 ID 数组,每次最多可传 60 个用户 ID。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
data.newmembersArray添加成功的用户 ID 数组。
data.actionString执行的操作内容。在该响应中,该字段的值为 add_member,表示添加用户。
data.idString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "usernames": [
     "user1","user2"
   ]
 }' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users'
响应示例
{
  "action": "post",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users",
  "entities": [],
  "data": {
    "newmembers": ["user1", "user2"],
    "action": "add_member",
    "id": "66XXXX33"
  },
  "timestamp": 1542554537237,
  "duration": 9,
  "organization": "XXXX",
  "applicationName": "testapp"
}

移除单个聊天室成员

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
data.resultBool是否成功移出聊天室成员:
- true:是;
- false:否。
data.actionString执行的操作。在该响应中,该字段的值为 remove_member,表示移除聊天室成员。
data.userString用户 ID。
data.idString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1'
响应示例
{
  "action": "delete",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_member",
    "user": "user1",
    "id": "66XXXX33"
  },
  "timestamp": 1542555744726,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}

批量移除聊天室成员

从聊天室移除多个成员,单次请求最多可移除 100 个成员。如果被移除用户不在聊天室中或聊天室不存在,将返回错误。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}
路径参数
参数类型是否必需描述
usernameString要移除的一个或多个用户 ID。每次最多可传 100 个用户 ID,用户 ID 之间用英文逗号(",")分隔,逗号在 URL 中转义为 "%2C"。

其他字段及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
dataJSON Array响应数据。
- resultBool是否成功批量移除聊天室成员:
- true:是;
- false:否。
- actionString执行的操作。在该响应中,该字段的值为 remove_member,表示移除成员。
- reasonString移除失败的原因。
- userString已删除成员的用户 ID 列表。
- idString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1%2Cuser2'
响应示例
{
  "action": "delete",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/users/user1%2Cuser2",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "remove_member",
      "reason": "user: user1 doesn't exist in group: 66XXXX33",
      "user": "user1",
      "id": "66XXXX33"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user2",
      "id": "66XXXX33"
    }
  ],
  "timestamp": 1542556177147,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

获取聊天室管理员列表

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
dataArray聊天室管理员用户 ID 数组。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin",
  "entities": [],
  "data": ["user1"],
  "timestamp": 1489073361210,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 1
}

添加聊天室管理员

将一个聊天室成员设置为聊天室管理员。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。填入 application/json
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数描述
newadmin要添加为聊天室管理员的成员用户 ID。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
data.resultBool操作结果:
- success:添加成功;
- false:添加失败。
data.newadminString添加为聊天室管理员的成员用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin -d '{"newadmin":"user1"}' -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "post",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin",
  "entities": [],
  "data": {
    "result": "success",
    "newadmin": "user1"
  },
  "timestamp": 1489073130083,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}

移除聊天室管理员

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

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}
路径参数
参数类型是否必需描述
oldadminString被撤销管理权限的管理员用户 ID。

其他字段及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.resultBool是否成功撤销聊天室管理员的管理权限:
- true:是;
- false:否。
data.oldadminString被撤销管理权限的管理员用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin/user1 -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/admin/user1",
  "entities": [],
  "data": {
    "result": "success",
    "oldadmin": "user1"
  },
  "timestamp": 1489073432732,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}

管理黑名单

环信即时通讯 IM 提供多个接口实现聊天室黑名单管理,包括查看黑名单中的用户以及将用户添加至和移出黑名单等操作。

查询聊天室黑名单

查询一个聊天室黑名单中的用户列表。黑名单中的用户无法查看或收到该聊天室的信息。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataArray聊天室黑名单中的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users'
响应示例
{
  "action": "get",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users",
  "entities": [],
  "data": ["user2", "user3"],
  "timestamp": 1543466293681,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 2
}

添加单个用户至聊天室黑名单

将单个用户加入指定聊天室的黑名单。聊天室所有者无法被加入聊天室的黑名单。

用户进入聊天室黑名单后,无法查看和收发该聊天室的信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.resultBool是否成功将用户添加至聊天室黑名单:
- true:是;
- false:否。
data.actionString执行的操作。在该响应中,该字段的值为 add_blocks,表示向聊天室黑名单中添加用户。
data.userString添加的用户 ID。
data.chatroomidString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1'
响应示例
{
  "action": "post",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_blocks",
    "user": "user1",
    "chatroomid": "66XXXX33"
  },
  "timestamp": 1542539577124,
  "duration": 27,
  "organization": "XXXX",
  "applicationName": "testapp"
}

批量添加用户至聊天室黑名单

将多个用户加入指定聊天室的黑名单。你一次最多可以添加 60 个用户至聊天室黑名单。聊天室所有者无法被加入聊天室的黑名单。

用户进入聊天室黑名单后,无法查看和收发该聊天室的信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型描述
usernamesArray待添加到聊天室黑名单的用户 ID,最多可添加 60 个。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBool是否成功批量添加用户至聊天室黑名单:
- true:是;
- false:否。
- actionString执行的操作。在该响应中,该字段的值为 add_blocks,表示向聊天室黑名单中添加用户。
- reasonString添加失败的原因。
- userString添加的用户 ID。
- chatroomidString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "usernames": [
     "user3",
     "user4"
   ]
 }' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users'
响应示例
{
  "action": "post",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "add_blocks",
      "reason": "user: user3 doesn't exist in chatroom: 66XXXX33",
      "user": "user3",
      "chatroomid": "66XXXX33"
    },
    {
      "result": true,
      "action": "add_blocks",
      "user": "user4",
      "chatroomid": "66XXXX33"
    }
  ],
  "timestamp": 1542540095540,
  "duration": 16,
  "organization": "XXXX",
  "applicationName": "testapp"
}

从聊天室黑名单移出单个用户

将指定用户移出聊天室黑名单。对于聊天室黑名单中的用户,如果需要将其再次加入聊天室,需要先将其从聊天室黑名单中移除。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.resultBool是否成功将该用户移出聊天室黑名单:
- true:是;
- false:否。
data.chatroomidString聊天室 ID。
data.actionString执行的操作。在该响应中,该字段的值为 remove_blocks,表示将用户移出聊天室黑名单。
data.userString被移除的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1'
响应示例
{
  "action": "delete",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_blocks",
    "user": "user1",
    "chatroomid": "66XXXX33"
  },
  "timestamp": 1542540470679,
  "duration": 45,
  "organization": "XXXX",
  "applicationName": "testapp"
}

从聊天室黑名单批量移除用户

将多名指定用户从聊天室黑名单中移除。你每次最多可移除 60 个用户。对于聊天室黑名单中的用户,如果需要将其再次加入聊天室,需要先将其从聊天室黑名单中移除。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{usernames}
路径参数
参数类型是否必需描述
usernameString要移出聊天室黑名单的用户 ID,每次最多可传 60 个。用户 ID 之间以英文逗号(",")分隔,逗号在 URL 中转义为 "%2C"。

其他字段及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBool是否成功将用户批量移出聊天室黑名单:
- true:是;
- false:否。
- actionString执行的操作。在该响应中,该字段的值为 remove_blocks,表示将用户移出聊天室黑名单。
- userString被移除的用户 ID。
- chatroomidString聊天室 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1%2Cuser2'
响应示例
{
  "action": "delete",
  "application": "8beXXXX02",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/blocks/users/user1%2Cuser2",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "remove_blocks",
      "user": "user1",
      "chatroomid": "66XXXX33"
    },
    {
      "result": true,
      "action": "remove_blocks",
      "user": "user2",
      "chatroomid": "66XXXX33"
    }
  ],
  "timestamp": 1542541014655,
  "duration": 29,
  "organization": "XXXX",
  "applicationName": "testapp"
}

管理白名单

环信即时通讯 IM 提供多个接口实现聊天室白名单管理,包括查看白名单中的用户以及将用户添加至和移出白名单等。

聊天室白名单中的成员在聊天室中发送的消息为高优先级,会优先送达,但不保证必达。当负载较高时,服务器会优先丢弃低优先级的消息。若即便如此负载仍很高,服务器也会丢弃高优先级消息。

查询聊天室白名单

查询一个聊天室白名单中的用户列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataArray聊天室白名单中的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/white/users'
响应示例
{
  "action": "get",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/white/users",
  "entities": [],
  "data": ["wzy_test", "wzy_vivo", "wzy_huawei", "wzy_xiaomi", "wzy_meizu"],
  "timestamp": 1594724947117,
  "duration": 3,
  "organization": "XXXX",
  "applicationName": "testapp",
  "count": 5
}

添加单个用户至聊天室白名单

将单个用户添加至聊天室白名单。用户添加至聊天室白名单后,当聊天室全员禁言时,仍可以在聊天室中发送消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users/{username}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.resultBool是否成功将单个用户添加至聊天室白名单:
- true:是;
- false:否。
data.chatroomidString聊天室 ID。
data.actionString执行操作。在该响应中,该字段的值为 add_user_whitelist,表示将用户添加至聊天室白名单中。
data.userString添加的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/{66XXXX33}/white/users/{username}'
响应示例
{
  "action": "post",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/white/users/wzy_xiaomi",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_user_whitelist",
    "user": "wzy_xiaomi",
    "chatroomid": "66XXXX33"
  },
  "timestamp": 1594724293063,
  "duration": 4,
  "organization": "XXXX",
  "applicationName": "testapp"
}

批量添加用户至聊天室白名单

添加多个用户至聊天室白名单。你一次最多可添加 60 个用户。用户添加至聊天室白名单后,在聊天室全员禁言时,仍可以在聊天室中发送消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型描述
usernamesArray待添加至聊天室白名单中的用户 ID,每次最多可传 60 个。

其他字段及描述详见 公共参数

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBool是否成功将用户批量添加至聊天室白名单:
- true:是;
- false:否。
- reasonString添加失败的原因。
- chatroomidString聊天室 ID。
- actionString执行的操作。在该响应中,该字段的值为 add_user_whitelist,表示添加用户至聊天室白名单。
- userString添加至聊天室白名单中的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{"usernames" : ["user1"]}' 'https://XXXX/XXXX/XXXX/chatrooms/{chatroomid}/white/users'
响应示例
{
  "action": "post",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/white/users",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "add_user_whitelist",
      "user": "wzy_test",
      "chatroomid": "66XXXX33"
    },
    {
      "result": true,
      "action": "add_user_whitelist",
      "user": "wzy_meizu",
      "chatroomid": "66XXXX33"
    }
  ],
  "timestamp": 1594724634191,
  "duration": 2,
  "organization": "XXXX",
  "applicationName": "testapp"
}

将用户移出聊天室白名单

将指定用户从聊天室白名单移除。你每次最多可移除 60 个用户。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users/{username}
路径参数
参数类型描述是否必填
usernamesString要从聊天室白名单中移除的用户 ID,最多可传 60 个,用户 ID 之间以英文逗号(",")分隔。

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBool是否成功将用户移出聊天室白名单:
- true:是;
- false:否。
- chatroomidString聊天室 ID。
- actionString执行的操作。在该响应中,该字段的值为 remove_user_whitelist,表示将用户移出聊天室白名单。
- userString移除聊天室白名单的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/{66XXXX33}/white/users/{username}'
响应示例
{
  "action": "delete",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/66XXXX33/white/users/wzy_huawei,wzy_meizu",
  "entities": [],
  "data": [
    {
      "result": true,
      "action": "remove_user_whitelist",
      "user": "wzy_huawei",
      "chatroomid": "66XXXX33"
    },
    {
      "result": true,
      "action": "remove_user_whitelist",
      "user": "wzy_meizu",
      "chatroomid": "66XXXX33"
    }
  ],
  "timestamp": 1594725137704,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

管理禁言

环信即时通讯 IM 提供多个管理聊天室禁言列表的接口,包括获取禁言列表以及将用户添加至或移出禁言列表等。

获取禁言列表

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

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- expireLong禁言到期的 Unix 时间戳,单位为毫秒。
- userString被禁言的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET HTTP://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "get",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute",
  "entities": [],
  "data": [
    {
      "expire": 1489158589481,
      "user": "user1"
    },
    {
      "expire": 1489158589481,
      "user": "user2"
    }
  ],
  "timestamp": 1489072802179,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

禁言聊天室成员

禁言单个或多个聊天室成员。你一次最多可禁言 60 个成员。

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
mute_durationLong禁言时长,从当前时间开始计算。单位为毫秒。-1 表示永久禁言。
usernamesArray要被禁言的用户 ID,一次最多可传 60 个。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBool是否成功禁言用户:
- true:是;
- false:否。
- expireLong禁言到期时间,Unix 时间戳,单位为毫秒。
- userString被禁言的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d
'{
    "usernames": [
        "user1",
        "user2"
    ],
    "mute_duration": 86400000
}'https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute'
响应示例
{
  "action": "post",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute",
  "entities": [],
  "data": [
    {
      "result": true,
      "expire": 1642148173726,
      "user": "user1"
    },
    {
      "result": true,
      "expire": 1642148173726,
      "user": "user2"
    }
  ],
  "timestamp": 1489072189508,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

禁言聊天室全体成员

对所有聊天室成员一键禁言。该操作不影响聊天室禁言列表,即一键禁言不会将聊天室所有成员加入聊天室禁言列表。

设置聊天室全员禁言后,仅聊天室白名单中的用户可在聊天室内发消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/ban
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.muteBool是否处于聊天室全员禁言状态:
- true:是;
- false:否。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/ban'
响应示例
{
  "action": "put",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/ban",
  "entities": [],
  "data": {
    "mute": true
  },
  "timestamp": 1594628861058,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}

解除聊天室禁言成员

解除对一个或多个聊天室成员的禁言。你一次最多可对 60 个成员解除禁言。

解除禁言后,该成员可以正常在聊天室中发送消息。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute/{member1}(,{member2},…)
路径参数
参数类型是否必需描述
member1String待被移出禁言列表的聊天室成员的用户 ID。
一次最多可传 60 个用户 ID,用户 ID 之间用英文逗号(",")隔开,逗号在 URL 中转义为 "%2C"。

其他字段及描述详见 公共参数

请求 header
参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
dataJSON Array响应数据。
- resultBoolean是否成功将指定用户移出禁言列表:
- true:是;
- false:否。
- userString被解除禁言的聊天室成员的用户 ID。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE HTTP://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute/user1  -H 'Authorization: Bearer <YourAppToken>'
响应示例
{
  "action": "delete",
  "application": "52XXXXf0",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/mute/user1",
  "entities": [],
  "data": [
    {
      "result": true,
      "user": "user1"
    }
  ],
  "timestamp": 1489072695859,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "testapp"
}

解除聊天室全员禁言

一键取消对聊天室全体成员的禁言。解除禁言后,聊天室成员可以在聊天室中正常发送消息。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/ban
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段类型描述
data.muteBool是否处于聊天室全员禁言状态:
- true:是;
- false:否。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/ban'
响应示例
{
  "action": "delete",
  "application": "5cXXXX75d",
  "uri": "https://XXXX/XXXX/XXXX/chatrooms/12XXXX11/ban",
  "entities": [],
  "data": {
    "mute": false
  },
  "timestamp": 1594628899502,
  "duration": 1,
  "organization": "XXXX",
  "applicationName": "testapp"
}