用户体系集成
更新时间:2022-07-07
本文展示如何调用环信即时通讯 RESTful API 实现用户体系建立和管理,包括用户注册、获取、修改、删除、封禁、解禁、强制下线等。
前提条件
要调用环信即时通讯 RESTful API,请确保满足以下要求:
- 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
- 已从服务端获取 app token,详见 使用环信 app token 鉴权。
- 了解环信 IM API 的调用频率限制,详见接口频率限制。
公共参数
以下表格列举了环信即时通讯 RESTful API 的公共请求参数和响应参数:
请求参数
参数 | 类型 | 描述 |
---|---|---|
host | String | 你在环信即时通讯云控制台注册项目时所在的 集群服务器地址。 |
org_name | String | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
响应参数
参数 | 类型 | 描述 |
---|---|---|
action | String | 请求方式。 |
organization | String | 即 org_name ,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
application | String | 系统内为应用生成的唯一标识,开发者无需关心。 |
applicationName | String | 即 app_name ,你在环信即时通讯云控制台注册项目时填入的应用名称。 |
uri | String | 请求 URL。 |
path | String | 请求路径,属于请求 URL 的一部分,开发者无需关注。 |
entities | JSON | 详细信息。 |
entities.uuid | String | 用户的 UUID。即时通讯服务为该请求中的 app 或用户生成的唯一内部标识,用于生成 User Token。 |
entities.type | String | 对象类型,无需关注。 |
entities.created | Long | 注册用户的 Unix 时间戳,单位为毫秒。 |
entities.modified | Long | 最近一次修改用户信息的 Unix 时间戳,单位为毫秒。 |
entities.username | String | 用户 ID,长度不可超过 64 个字节。 |
entities.activated | Bool | 用户是否为活跃状态: - true :用户为活跃状态。- false :用户为封禁状态。如要使用已被封禁的用户账户,你需要调用解禁用户解除封禁。 |
data | JSON | 实际获取的数据详情。 |
timestamp | Long | HTTP 响应的 Unix 时间戳,单位为毫秒。 |
duration | Int | 从发送 HTTP 请求到响应的时长, 单位为毫秒。 |
认证方式
环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。本文介绍的即时通讯所有 REST API 均需使用 App Token 的鉴权方式,详见 使用 Token 鉴权。
注册用户
注册单个用户
注册一个用户。
注册单个用户,需要授权注册模式。推荐授权注册模式,即注册环信即时通讯 IM 账号时,必须携带管理员身份认证信息。利用授权注册模式,可防止已获取了注册 URL 和知晓注册流程的某些人恶意向服务器大量注册垃圾用户。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
username | String | 是 | 用户 ID,长度不可超过 64 个字节长度。不可设置为空。支持以下字符集: • 26 个小写英文字母 a-z; • 26 个大写英文字母 A-Z; • 10 个数字 0-9; • “_”, “-”, “.”。 注意: • 该参数不区分大小写,因此 Aa 和 aa 为相同用户名; • 请确保同一个 app 下, username 唯一; • username 用户 ID 是会公开的信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。 |
password | String | 是 | 用户的登录密码,长度不可超过 64 个字符。 |
nickname | String | 否 | 推送消息时,在消息推送通知栏内显示的用户昵称,并非用户个人信息的昵称。长度不可超过 100 个字符。支持以下字符集: • 26 个小写英文字母 a-z; • 26 个大写英文字母 A-Z; • 10 个数字 0-9; • 中文; • 特殊字符。 |
其他参数及说明详见公共参数。
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
entities.username | String | 用户 ID。 |
entities.password | String | 用户的登录密码。 |
entities.nickname | String | 推送消息时,在消息推送通知栏内显示的用户昵称。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '[
{
"username": "user1",
"password": "123",
"nickname": "testuser"
}
]' 'https://XXXX/XXXX/XXXX/users'
响应示例
{
"action": "post",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"path": "/users",
"uri": "https://XXXX/XXXX/XXXX/users",
"entities": [
{
"uuid": "0ffe2d80-XXXX-XXXX-8d66-279e3e1c214b",
"type": "user",
"created": 1542795196504,
"modified": 1542795196504,
"username": "user1",
"activated": true,
"nickname": "testuser"
}
],
"timestamp": 1542795196515,
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"
}
批量注册用户
批量注册是授权注册方式,服务端需要校验有效的 token 权限才能进行操作。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求 body
一个请求内最多可注册 60 个用户 ID。
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
username | String | 是 | 用户 ID,长度不能超过 64 个字节。 |
password | String | 是 | 用户的登录密码,长度不可超过 64 个字符。 |
nickname | String | 否 | 推送消息时,在消息推送通知栏内显示的用户昵称,并非用户个人信息的昵称。长度不可超过 100 个字符。支持以下字符集: • 26 个小写英文字母 a-z; • 26 个大写英文字母 A-Z; • 10 个数字 0-9; • 中文; • 特殊字符。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
entities.username | String | 用户 ID。 |
entities.nickname | String | 推送消息时,在消息推送通知栏内显示的用户昵称。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例一
注册 2 个用户:
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H "Authorization: Bearer <YourAppToken>" -i "https://XXXX/XXXX/XXXX/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}]'
响应示例一
{
"action": "post",
"application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
"path": "/users",
"uri": "https://XXXX/XXXX/XXXX/users",
"entities": [
{
"uuid": "278b5e60-XXXX-XXXX-8f9b-d5d83ebec806",
"type": "user",
"created": 1541587920710,
"modified": 1541587920710,
"username": "user1",
"activated": true,
"nickname": "testuser1"
},
{
"uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
"type": "user",
"created": 1541587920712,
"modified": 1541587920712,
"username": "user2",
"activated": true,
"nickname": "testuser2"
} ],
"timestamp": 1541587920714,
"data": [],
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"
}
请求示例二
当请求 body 中存在已经注册过的用户 user 3 时,user 3 注册失败并在响应 body 中的 data 数组内返回,用户 user 1、user 2 仍然注册成功。
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H "Authorization: Bearer <YourAppToken>" -i "https://XXXX/XXXX/XXXX/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}, {"username":"user3", "password":"789","nickname":"testuser3"}]'
响应示例二
{
"action": "post",
"application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
"path": "/users",
"uri": "https://XXXX/XXXX/XXXX/testapp/users",
"entities": [
{
"uuid": "278b5e60-XXXX-XXXX-8f9b-d5d83ebec806",
"type": "user",
"created": 1541587920710,
"modified": 1541587920710,
"username": "user1",
"activated": true,
"nickname": "testuser1"
},
{
"uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
"type": "user",
"created": 1541587920712,
"modified": 1541587920712,
"username": "user2",
"activated": true,
"nickname": "testuser2" } ],
"timestamp": 1541587920714,
"data": [ {
"username": "user3",
"registerUserFailReason":
"the user3 already exists"
} ],
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"}
获取用户详情
获取单个用户的详情
获取单个应用用户的详细信息接口。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users/{username}
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示成功获取 token,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
entities.username | String | 用户 ID。 |
entities.nickname | String | 推送消息时,在消息推送通知栏内显示的用户昵称。 |
entities.notification_display_style | Int | 消息推送方式: - “0”:仅通知; - “1”:通知以及消息详情,没有设置返不会返回。 |
entities.notification_no_disturbing | Bool | 是否开启免打扰。 - true :免打扰开启。若用户未设该参数,则响应中不返回。- false :免打扰关闭。 |
entities.notification_no_disturbing_start | String | 免打扰的开始时间。例如,“8” 代表每日 8:00 开启免打扰。若用户未设该参数,则响应中不返回。 |
entities.notification_no_disturbing_end | String | 免打扰的结束时间。例如,“18” 代表每日 18:00 关闭免打扰。若用户未设该参数,则响应中不返回。 |
entities.notification_ignore_63112447328257 | Bool | 是否屏蔽了群组消息的离线推送的设置。参数中的数字表示群组 ID。 - true :已屏蔽。- false :未屏蔽。若用户未设该参数,则响应中不返回。 |
entities.notifier_name | String | 客户端推送证书名称。若用户未设置推送证书名称,则响应中不返回。 |
entities.device_token | String | 推送 token。若用户没有推送 token,则响应中不返回。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/XXXX'
响应示例
{
"action": "get",
"path": "/users",
"uri": "http://XXXX/XXXX/XXXX/users/XXXX",
"entities": [
{
"uuid": "0ffe2d80-XXXX-XXXX-8d66-279e3e1c214b",
"type": "user",
"created": 1542795196504,
"modified": 1542795196504,
"username": "XXXX",
"activated": true,
"nickname": "testuser"
} ],
"timestamp": 1542798985011,
"duration": 6,
"count": 1
}
批量获取用户详情
该接口查询多个用户的信息列表,按照用户创建时间顺序返回。你可以指定要查询的用户数量(limit)。
若数据库中的用户数量大于你要查询的用户数量(limit),返回的信息中会携带游标 “cursor” 标示下次数据获取的开始位置。你可以分页获取多个用户的详情,直到返回的信息中不再包含 cursor,即已经达到最后一页。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users?limit={N}&{cursor}
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
limit | Int | 否 | 请求查询用户的数量。取值范围[1,100],默认值为 10。若实际用户数量超过 100,返回 100 个用户。 |
cursor | String | 否 | 开始获取数据的游标位置,用于分页显示用户列表。第一次发起批量查询用户请求时若不设置 cursor ,请求成功后会获得第一页用户列表。从响应 body 中获取 cursor ,并在下一次请求的 URL 中传入该 cursor ,直到响应 body 中不再有 cursor 字段,则表示已查询到 app 中所有用户。 |
其他参数及说明详见公共参数。
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
entities.username | String | 用户 ID。 |
entities.nickname | String | 推送消息时,在消息推送通知栏内显示的用户昵称。 |
entities.notification_display_style | Int | 消息推送方式: - “0”:仅通知; - “1”:通知以及消息详情。若用户未设置该参数,则响应中不会返回。 |
entities.notification_no_disturbing | Bool | 是否开启免打扰模式。 - true :免打扰开启。若用户未设置改参数,则响应中不返回。- false :代表免打扰关闭。 |
entities.notification_no_disturbing_start | String | 免打扰的开始时间。例如, “8” 代表每日 8:00 开启免打扰。若用户未设该参数,则响应中不返回。 |
entities.notification_no_disturbing_end | String | 免打扰的结束时间。例如, “18” 代表每日 18:00 关闭免打扰。若用户未设该参数,则响应中不返回。 |
entities.notification_ignore_63112447328257 | Bool | 是否屏蔽了群组消息的离线推送的设置。数字表示群组 ID。 - true :已屏蔽。 - false :未屏蔽,没有设置则不会返回。 |
entities.notifier_name | String | 客户端推送证书名称。若用户未设置推送证书名称,则响应中不返回。 |
entities.device_token | String | 推送 token。若用户没有推送 token,则响应中不返回。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例一
按照注册时间的顺序查询 2 个用户的信息列表:
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users?limit=2'
使用返回的 cursor 获取下一页
将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users?limit=2&cursor=LTgzXXXX2tB'
响应示例一
返回注册时间较早的 2 个 用户的信息列表:
{
"action": "get",
"params":
{
"limit": [ "2" ]
},
"path": "/users",
"uri": "http://XXXX/XXXX/XXXX/users",
"entities": [
{
"uuid": "ab90eff0-XXXX-XXXX-9174-8f161649a182",
"type": "user",
"created": 1542356511855,
"modified": 1542356511855,
"username": "XXXX",
"activated": true,
"nickname": "user1"
},
{
"uuid": "b2aade90-XXXX-XXXX-a974-f3368f82e4f1",
"type": "user",
"created": 1542356523769,
"modified": 1542356523769,
"username": "user2",
"activated": true,
"nickname": "user2"
} ],
"timestamp": 1542558467056,
"duration": 11,
"cursor": "LTgzXXXX2tB",
"count": 2
}
请求示例二
使用响应示例一中的 cursor,继续按照注册时间的顺序查询下一页用户列表,该页面用户数量为 2:
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users?limit=2&cursor=LTgzXXXX 2tB'
响应示例二
继续返回 2 个 用户的信息列表:
{
"action": "get",
"params":
{
"cursor": [
"LTgzXXXX2tB"
],
"limit": [
"2" ]
},
"path": "/users",
"uri": "http://XXXX/XXXX/XXXX/users",
"entities": [
{
"uuid": "fef7f250-XXXX-XXXX-ba39-0fed7dcc3cdd",
"type": "user",
"created": 1542361376245,
"modified": 1542361376245,
"username": "XXXX",
"activated": true,
"nickname": "testuser"
} ],
"timestamp": 1542559337702,
"duration": 2,
"count": 1
}
删除用户账号
删除单个用户
删除一个用户。如果此用户是群主或者聊天室所有者,系统会同时删除对应的群组和聊天室。请在操作时进行确认。
HTTP 请求
DELETE https://{host}/{org_name}/{app_name}/users/{username}
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
entities.username | String | 删除的用户的 ID。 |
entities.nickname | String | 删除的用户的昵称。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1'
响应示例
{
"action": "delete",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"path": "/users",
"uri": "https://XXXX/XXXX/XXXX/users",
"entities": [
{
"uuid": "ab90eff0-XXXX-XXXX-9174-8f161649a182",
"type": "user",
"created": 1542356511855,
"modified": 1542356511855,
"username": "XXXX",
"activated": true,
"nickname": "user1"
} ],
"timestamp": 1542559539776,
"duration": 39,
"organization": "XXXX",
"applicationName": "XXXX"
}
批量删除用户
删除某个 App 下指定数量的用户账号。建议一次删除的用户数量不要超过 100。需要注意的是,这里只指定了要删除的用户数量,并未指定要删除的具体用户,你可以在响应中查看删除的用户。
如果删除的多个用户中包含群组或者聊天室的管理员,该用户管理的群组和聊天室也会相应被删除。
HTTP 请求
DELETE https://{host}/{org_name}/{app_name}/users
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
entities.username | String | 删除的用户的 ID。 |
entities.nickname | String | 删除的用户的昵称。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users?limit=2'
响应示例
{
"action": "delete",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"params": {
"limit": [
"2"
]
},
"path": "/users",
"uri": "https://XXXX/XXXX/testapp/users",
"entities": [
{
"uuid": "b2aade90-XXXX-XXXX-a974-f3368f82e4f1",
"type": "user",
"created": 1542356523769,
"modified": 1542597334500,
"username": "user2",
"activated": true,
"nickname": "testuser"
},
{
"uuid": "b98ad170-XXXX-XXXX-XXXX-7f76daa76557",
"type": "user",
"created": 1542356535303,
"modified": 1542356535303,
"username": "user3",
"activated": true,
"nickname": "user3"
}
],
"timestamp": 1542867197779,
"duration": 504,
"organization": "XXXX",
"applicationName": "testapp",
"cursor": "LTgXXXXDNR"
}
修改用户密码
修改用户密码
可以通过服务端接口修改用户的登录密码,不需要提供原密码。
HTTP 请求
PUT https://{host}/{org_name}/{app_name}/users/{username}/password
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求 body
HTTP 响应
响应 body
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token,<YourPassword> 替换为你设置的新密码
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{ "newpassword": "<YourPassword>" }' 'http://XXXX/XXXX/XXXX/users/user1/password'
响应示例
{
"action": "set user password",
"timestamp": 1542595598924,
"duration": 8}
获取单个用户在线状态(status)
查看一个用户的在线状态。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users/{username}/status
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data.username | String | 数据格式为:“用户名:当前在线状态”,例如,user1 的在线和离线状态分别为 “user1”: “online” 和”user1”: “offline”。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/status'
响应示例
{
"action": "get",
"uri": "http://XXXX/XXXX/XXXX/users/user1/status",
"entities": [],
"data": {
"user1": "offline"
},
"timestamp": 1542601284531,
"duration": 4,
"count": 0
}
获取用户在线状态(status)
批量获取用户在线状态(status)
批量查看用户的在线状态,最多可同时查看 100 个用户的状态。
HTTP 请求
POST https://{host}{org_name}/{app_name}/users/batch/status
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
usernames | String | 是 | 要查询状态的用户 ID,以数组方式提交,最多不能超过 100 个。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data.username | String | 数据格式为:“用户 ID:当前在线状态”,例如,user1 的在线和离线状态分别为 “user1”: “online” 和”user1”: “offline”。 |
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST http://XXXX/XXXX/chatdemoui/users/batch/status -H 'Authorization: Bearer <YourAppToken>' -H 'Content-Type: application/json' -d '{"usernames":["user1","user2"]}'
响应示例
该接口不对用户 ID 进行校验。若查询不存在的用户 ID 的状态,则返回的状态为 offline。
{
"action": "get batch user status",
"data": [
{
"user1": "offline"
},
{
"user2": "offline"
}
],
"timestamp": 1552280231926,
"duration": 4
}
用户全局禁言
随着监管机制日益完善,对 app 的监管不断加强,安全合规逐渐成为 app 的生命线。
为加强 app 管理,环信即时通讯提供全局禁言功能,对 app 提供用户 ID 级别的禁言管理,支持在管理员发现用户违规后进行全局禁言,以维护 app 良好的内容生态环境。禁言到期后,服务器会自动解除禁言,恢复该用户发送消息的权限。
你可以对单个用户 ID 设置单聊、群组或聊天室消息全局禁言。禁言后,该用户将无法在对应的单聊、群组或聊天室发送消息;无论通过调用客户端 API,还是使用服务端 RESTful API 都不行。
该功能可广泛应用于实时互动 app 中,例如发现某用户频繁向多个聊天室发送违规广告,则可以对该用户开启全局聊天室禁言 15 天;发现某用户发表触犯红线的政治言论,则可以全局永久禁言,用户申诉通过后可以解禁。
设置用户全局禁言
设置单个用户 ID 的单聊、群组、聊天室消息全局禁言。
HTTP 请求
POST https://{host}/{orgName}/{appName}/mutes
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | 鉴权 token,管理员 token(含)以上权限。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
username | String | 是 | 设置禁言配置的用户 ID。 |
chat | Int | 否 | 单聊消息禁言时长,单位为秒,最大值为 2147483647。 - > 0 :该用户 ID 具体的单聊消息禁言时长。 - 0 :取消该用户的单聊消息禁言。- -1 :该用户被设置永久单聊消息禁言。- 其他负值无效。 |
groupchat | Int | 否 | 群组消息禁言时长,单位为秒,规则同上。 |
chatroom | Int | 否 | 聊天室消息禁言时长,单位为秒,规则同上。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data.result | String | 该方法调用结果。ok 表示设置成功。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X POST 'https://XXXX/XXXX/XXXX/mutes' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json' \
--data-raw '{
"username": "zs1",
"chat": 100,
"groupchat": 100,
"chatroom": 100
}'
响应示例
{
"path": "/mutes",
"uri": "https://XXXX/XXXX/XXXX/mutes",
"timestamp": 1631609754727,
"organization": "XXXX",
"application": "357169f0-XXXX-XXXX-9b3a-f1af649cc48d",
"action": "post",
"data": {
"result": "ok"
},
"duration": 74,
"applicationName": "XXXX"
}
查询单个用户 ID 全局禁言
查询单个用户的单聊、群聊和聊天室消息的禁言。
HTTP 请求
GET https://{host}/{orgName}/{appName}/mutes/{username}
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | application/json 内容类型。 |
Authorization | String | 是 | 鉴权 token,管理员 token (含)以上权限。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data.userid | String | 设置禁言的用户 ID。 |
data.chat | Int | 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。 - > 0:该用户 ID 具体的单聊消息禁言时长。 - 0 :该用户的单聊消息禁言已取消。 - -1 :该用户被设置永久单聊消息禁言。 |
data.groupchat | Int | 群组消息剩余禁言时长,单位为秒,规则同上。 |
data.chatroom | Int | 聊天室消息剩余禁言时长,单位为秒,规则同上。 |
data.unixtime | Int | 当前操作的 Unix 时间戳。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'https://XXXX/XXXX/XXXX/mutes/zs1' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json'
响应示例
{
"path": "/mutes",
"uri": "https://XXXX/XXXX/XXXX/mutes",
"timestamp": 1631609831800,
"organization": "XXXX",
"application": "357169f0-XXXX-XXXX-9b3a-f1af649cc48d",
"action": "get",
"data": {
"userid": "XXXX#restys_zs1",
"chat": 96,
"groupchat": 96,
"chatroom": 96,
"unixtime": 1631609831
},
"duration": 13,
"applicationName": "XXXX"
}
查询 app 下的所有全局禁言的用户
该方法查询 app 下所有全局禁言的用户及其禁言剩余时间。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | 鉴权 token,管理员 token(含)以上权限。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
pageNum | Int | 是 | 请求查询的页码。 |
pageSize | Int | 是 | 请求查询每页显示的禁言用户的数量。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
username | String | 设置禁言的用户 ID。 |
chat | Int | 单聊消息剩余禁言时间,单位为秒。最大值为 2147483647。 - > 0:该用户 ID 具体的单聊消息禁言时长。 - 0 :该用户的单聊消息禁言已取消。 - -1 :该用户被设置永久单聊消息禁言。 |
groupchat | Int | 群组消息剩余禁言时长,单位为秒,规则同上。 |
chatroom | Int | 聊天室消息剩余禁言时长,单位为秒,规则同上。 |
unixtime | Int | 当前操作的 Unix 时间戳。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'https://XXXX/XXXX/XXXX/mutes?pageNum=1&pageSize=10' \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/json'
响应示例
{
"path": "/mutes",
"uri": "https://XXXX/XXXX/XXXX/mutes",
"timestamp": 1631609858771,
"organization": "XXXX",
"application": "357169f0-XXXX-XXXX-9b3a-f1af649cc48d",
"action": "get",
"data": {
"data": [
{
"username": "zs2",
"chatroom": 0
},
{
"username": "zs1",
"groupchat": 69
},
{
"username": "zs1",
"chat": 69
},
{
"username": "zs1",
"chatroom": 69
},
{
"username": "h2",
"chatroom": 0
},
{
"username": "h2",
"groupchat": 0
},
{
"username": "h2",
"chat": 0
}
],
"unixtime": 1631609858
},
"duration": 17,
"applicationName": "XXXX"
}
获取用户离线消息数据
获取用户离线消息数量
获取环信 IM 用户的离线消息数量。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users/{owner_username}/offline_msg_count
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
owner_username | String | 是 | 要获取离线消息数的用户 ID。 |
其他参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
username | String | 数据格式为:“用户 ID:当前离线消息的数量“,例如,”user1: 0”。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/offline_msg_count'
响应示例
{
"action": "get",
"uri": "http://XXXX/XXXX/XXXX/users/user1/offline_msg_count",
"entities": [],
"data": {
"user1": 0
},
"timestamp": 1542601518137,
"duration": 3,
"count": 0
}
获取某条离线消息状态
获取用户的离线消息的状态,即查看该消息是否已投递。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
username | String | 是 | 要获取离线消息状态的用户 ID。 |
msg_id | String | 是 | 要查看状态的离线消息 ID。 |
其他参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中的字段如下:
字段 | 类型 | 描述 |
---|---|---|
msg_id | String | 数据格式为“消息 ID”:“离线状态”。消息的离线状态有两种: - delivered :已投递;- undelivered :未投递。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123'
响应示例
{
"action": "get",
"uri": "http://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123",
"entities": [],
"data": {
"123": "delivered"
},
"timestamp": 1542601830084,
"duration": 5,
"count": 0
}
用户账号封禁、解禁和强制下线
账号封禁
环信即时通讯 IM 提供了对用户的禁用以及解禁接口操作,用户若被禁用将立即下线并无法登录进入环信即时通讯 IM,直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users/{username}/deactivate
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
username | String | 被封禁的用户 ID。 |
nickname | String | 被封禁的用户昵称。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/deactivate'
响应示例
{
"action": "Deactivate user",
"entities": [
{
"uuid": "4759aa70-XXXX-XXXX-925f-6fa0510823ba",
"type": "user",
"created": 1542595573399,
"modified": 1542597578147,
"username": "user1",
"activated": false,
"nickname": "user"
} ],
"timestamp": 1542602157258,
"duration": 12}
账号解禁
环信即时通讯 IM 提供了对用户的禁用以及解禁接口操作。对用户禁用后,用户将立即下线并无法登录进入环信即时通讯 IM,直到被解禁后才能恢复登录。该功能常于对异常用户的即时处理场景。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users/{username}/activate
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
action | String | 执行的操作。账号解禁为 activate user 。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/activate'
响应示例
{
"action": "activate user",
"timestamp": 1542602404132,
"duration": 9}
强制下线
强制用户即把用户状态改为离线,用户需要重新登录才能正常使用。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/users/{username}/disconnect
路径参数
参数及说明详见公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
result | Bool | 用户是否已被强制下线: - true :是;- false :否。 |
其他字段及说明详见公共参数。
如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考响应状态码了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/disconnect'
响应示例
{
"action": "get",
"uri": "http://XXXX/XXXX/XXXX/users/user1/disconnect",
"entities": [],
"data": {
"result": true
},
"timestamp": 1542602601332,
"duration": 6,
"count": 0}