用户体系集成

大约 38 分钟

用户体系集成

本文展示如何调用环信即时通讯 RESTful API 实现用户体系建立和管理,包括用户注册、获取、修改、删除、封禁、解禁、强制下线等。

公共参数

以下表格列举了环信 IM 的 RESTful 接口的公共请求参数和响应参数:

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息

响应参数

参数类型描述
actionString请求方法。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString系统内为应用生成的唯一标识,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
entitiesJSON Array响应实体。
- uuidString用户的 UUID。即时通讯服务为该请求中的 app 或用户生成的唯一内部标识,用于生成 User Token。
- typeString对象类型,无需关注。
- createdLong注册用户的 Unix 时间戳,单位为毫秒。
- modifiedLong最近一次修改用户信息的 Unix 时间戳,单位为毫秒。
- usernameString用户 ID。
- nicknameString推送消息时,在消息推送通知栏内显示的昵称。
- activatedBool用户是否为正常状态:
- true:用户为正常状态。
- false:用户为封禁状态。如要使用已被封禁的用户账户,你需要调用解禁用户方法解除封禁。
dataJSON实际获取的数据详情。
timestampLongHTTP 响应的 Unix 时间戳,单位为毫秒。
durationLong从发送 HTTP 请求到响应的时长, 单位为毫秒。

前提条件

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

认证方式

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

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。本文介绍的即时通讯所有 REST API 均需使用 App Token 的鉴权方式,详见 使用 App Token 鉴权

注册用户

开放注册单个用户

开放注册指用户可以在登录客户端 SDK 后自行通过账号密码注册账号。一般在体验 Demo 和测试开发环境时使用,使用前需先在环信即时通讯云控制后台open in new window打开相应应用的开放注册开关,即在控制台首页的 应用列表 下点击目标应用的 操作 一栏中的 查看,然后选择 即时通讯 > 服务概览,在页面的 设置 区域中将 用户注册模式 设置为 开放注册

HTTP 请求

POST https://{host}/{org_name}/{app_name}/users
请求 Header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
请求 body
参数类型是否必需描述
usernameString用户 ID,长度不可超过 64 个字节。不可设置为空。支持以下字符集:
- 26 个小写英文字母 a-z;
- 26 个大写英文字母 A-Z;
- 10 个数字 0-9;
- “_”, “-”, “.”。

注意


- 该参数不区分大小写,因此 Aaaa 为相同的用户 ID;
- 请确保同一个 app 下,用户 ID 唯一;
- 用户 ID 为公开信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。

passwordString用户的登录密码,长度不可超过 64 个字符。

其他参数及说明详见 公共参数

HTTP 响应

响应 body

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

响应字段及说明详见 公共参数

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

示例

请求示例
curl -X POST -i "https://XXXX.com/XXXX-demo/XXXX/users" -d '{"username":"user1","password":"123","nickname":"testuser"}'
响应示例
{
  "action": "post",
  "application": "8be024f0-e978-XXXX-XXXX-5d598d5f8402",
  "path": "/users",
  "uri": "https://XXXX.com/XXXX-demo/XXXX/users",
  "entities": [
    {
      "uuid": "0ffe2d80-XXXX-XXXX-8d66-279e3e1c214b",
      "type": "user",
      "created": 1542795196504,
      "modified": 1542795196504,
      "username": "user1",
      "activated": true
    }
  ],
  "timestamp": 1542795196515,
  "duration": 0,
  "organization": "XXXX-demo",
  "applicationName": "XXXX"
}

授权注册单个用户

授权注册模式指注册环信即时通讯 IM 账号时携带管理员身份认证信息,即 App Token。

要使用该注册方式,你需要在环信控制台进行如下配置:

在控制台首页的 应用列表 下点击目标应用的 操作 一栏中的 查看,然后选择 即时通讯 > 服务概览,在页面的 设置 区域中将用户注册模式设置授权注册,然后单击保存

推荐使用该模式,因为该模式较为安全,可防止已获取了注册 URL 和了解注册流程的某些人恶意向服务器大量注册垃圾用户。

HTTP 请求

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

参数及说明详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
usernameString用户 ID,长度不可超过 64 字节。不可设置为空。支持以下字符集:
- 26 个小写英文字母 a-z;
- 26 个大写英文字母 A-Z;
- 10 个数字 0-9;
- “_”, “-”, “.”。

注意


- 该参数不区分大小写,因此 Aaaa 为相同用户名;
- 请确保同一个 app 下,用户 ID 唯一;
- 用户 ID 为公开信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。

passwordString用户的登录密码,长度不可超过 64 个字符。

HTTP 响应

响应 body

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

响应字段及描述详见 公共参数

如果返回的 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"
   }
 ]' '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
    }
  ],
  "timestamp": 1542795196515,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

批量注册用户

批量注册为授权注册方式,服务端需要校验有效的 token 权限才能进行操作。

HTTP 请求

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

参数及说明详见 公共参数

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

提示

单次请求最多可注册 60 个用户 ID。

参数类型是否必需描述
usernameString用户 ID,长度不可超过 64 个字节。不可设置为空。支持以下字符集:
- 26 个小写英文字母 a-z;
- 26 个大写英文字母 A-Z;
- 10 个数字 0-9;
- “_”, “-”, “.”。

注意


- 该参数不区分大小写,因此 Aaaa 为相同用户名;
- 请确保同一个 app 下,用户 ID 唯一;
- 用户 ID 为公开信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。

passwordString用户的登录密码,长度不可超过 64 个字符。

HTTP 响应

响应 body

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

响应字段及描述详见 公共参数

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

示例

请求示例一

注册 2 个用户:

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

curl -X POST -H "Authorization: Bearer <YourAppToken>" -i  "https://XXXX/XXXX/XXXX/users" -d '[{"username":"user1", "password":"123"}, {"username":"user2", "password":"456"}]'
响应示例一
{
  "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
    },
    {
      "uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
      "type": "user",
      "created": 1541587920712,
      "modified": 1541587920712,
      "username": "user2",
      "activated": true
    }
  ],
  "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"}, {"username":"user2", "password":"456"}, {"username":"user3", "password":"789"}]'
响应示例二
{
  "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
    },
    {
      "uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
      "type": "user",
      "created": 1541587920712,
      "modified": 1541587920712,
      "username": "user2",
      "activated": true
    }
  ],
  "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
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array响应实体。
- notification_display_styleInt消息推送方式:
- 0:仅通知。推送标题为“您有一条新消息”,推送内容为“请点击查看”;
- 1:通知以及消息详情。推送标题为“您有一条新消息”,推送内容为发送人昵称和离线消息的内容。
若用户未设置该参数,则响应中不返回。
- notification_no_disturbingBoolean是否开启免打扰。
- true:免打扰开启。若用户未设置该参数,则响应中不返回。
- false:免打扰关闭。
- notification_no_disturbing_startString免打扰的开始时间。例如,“8” 代表每日 8:00 开启免打扰。若用户未设该参数,则响应中不返回。
- notification_no_disturbing_endString免打扰的结束时间。例如,“18” 代表每日 18:00 关闭免打扰。若用户未设该参数,则响应中不返回。
- notification_ignore_63112447328257Bool是否屏蔽了群组消息的离线推送的设置。参数中的数字,例如 63112447328257 表示群组 ID。
-true:已屏蔽。
- false:未屏蔽。若用户未设该参数,则响应中不返回。
- notifier_nameString客户端推送证书名称。若用户未设置推送证书名称,则响应中不返回。
- device_tokenString推送 token。若用户没有推送 token,则响应中不返回。
countInt用户数量。

其他字段及说明详见 公共参数

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/XXXX'
响应示例
{
  "action": "get",
  "path": "/users",
  "uri": "https://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),返回的信息中会携带游标 cursor 标示下次数据获取的开始位置。你可以分页获取多个用户的详情,直到返回的信息中不再包含 cursor,即已经达到最后一页。

HTTP 请求

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

参数及说明详见 公共参数

查询参数
参数类型是否必需描述
limitInt请求查询用户的数量。取值范围为 [1,100],默认值为 10。若实际用户数量超过 100,返回 100 个用户。
cursorString开始获取数据的游标位置,用于分页显示用户列表。第一次发起批量查询用户请求时若不设置 cursor,请求成功后会获得第一页用户列表。从响应 body 中获取 cursor,并在下一次请求的 URL 中传入该 cursor,直到响应 body 中不再有 cursor 字段,则表示已查询到 app 中所有用户。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array响应实体。
- notification_display_styleInt消息推送方式:
- 0:仅通知。推送标题为“您有一条新消息”,推送内容为“请点击查看”;
- 1:通知以及消息详情。推送标题为“您有一条新消息”,推送内容为发送人昵称和离线消息的内容。
若用户未设置该参数,则响应中不会返回。
- notification_no_disturbingBool是否开启免打扰模式。
- true:免打扰开启。若用户未设置改参数,则响应中不返回。
- false:代表免打扰关闭。
- notification_no_disturbing_startString免打扰的开始时间。例如,8 代表每日 8:00 开启免打扰。若用户未设该参数,则响应中不返回。
- notification_no_disturbing_endString免打扰的结束时间。例如,18 代表每日 18:00 关闭免打扰。若用户未设该参数,则响应中不返回。
- notification_ignore_63112447328257Bool是否屏蔽了群组消息的离线推送的设置。数字表示群组 ID。
-true:已屏蔽。
- false:未屏蔽,没有设置则不会返回。
- notifier_nameString客户端推送证书名称。若用户未设置推送证书名称,则响应中不返回。
- device_tokenString推送 token。若用户没有推送 token,则响应中不返回。
cursorString游标,用于分页显示用户列表。
第一次发起批量查询用户请求时无需设置 cursor,请求成功后,从响应 body 中获取 cursor,并在下一次请求的 URL 中传入该 cursor,直到响应 body 中不再有 cursor 字段,则表示已查询到 app 中所有用户。
countNumber返回用户数量。

其他字段及说明详见 公共参数

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

示例

请求示例一

按照注册时间的顺序查询 2 个用户的信息列表:

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users?limit=2'

使用返回的 cursor 获取下一页:

<YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users?limit=2&cursor=LTgzXXXX2tB'
响应示例一

返回注册时间较早的 2 个用户的信息列表:

{
  "action": "get",
  "params": {
    "limit": ["2"]
  },
  "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"
    },
    {
      "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>' 'https://XXXX/XXXX/XXXX/users?limit=2&cursor=LTgzXXXX  2tB'
响应示例二

继续返回 2 个 用户的信息列表:

{
  "action": "get",
  "params": {
    "cursor": ["LTgzXXXX2tB"],
    "limit": ["2"]
  },
  "path": "/users",
  "uri": "https://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
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

响应字段及描述详见 公共参数

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

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://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。

需要注意的是,这里只指定了要删除的用户数量,并未指定要删除的具体用户,你可以在响应中查看删除的用户。如果删除的多个用户中包含群组或者聊天室的管理员,该用户管理的群组和聊天室也会相应删除。若删除了群主或聊天室所有者,对应的群组或聊天室会解散。

提示

该 API 用于删除你在集成了即时通讯 IM 后上线前的测试阶段创建的用户。

HTTP 请求

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

参数及说明详见 公共参数

查询参数
参数类型是否必需描述
limitInt要删除的用户的数量。取值范围为 [1,100],默认值为 10
cursorString开始删除用户的游标位置。第一次批量删除时若不设置 cursor,请求成功后会从最先创建的用户开始删除 limit 指定的用户数量。从响应 body 中获取 cursor,并在下一次请求的 URL 中传入该 cursor,直到响应 body 中不再有 cursor 字段,则表示已完全删除 app 中的所有用户。
请求 header
参数类型是否必需描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

响应字段及说明详见 公共参数

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

示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://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-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

请求包体为 JSON Object 类型,包含以下字段:

参数类型是否必需描述
newpasswordString用户的新登录密码,长度不可超过 64 个字符。

其他参数及说明详见 公共参数

HTTP 响应

响应 body

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

参数类型描述
actionString执行的操作。在该响应中,该参数的值为 set user password,表示设置用户密码。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token,<YourPassword> 替换为你设置的新密码

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{ "newpassword": "<YourPassword>" }' 'https://XXXX/XXXX/XXXX/users/user1/password'

响应示例

{
  "action": "set user password",
  "timestamp": 1542595598924,
  "duration": 8
}

获取用户在线状态

获取单个用户在线状态

查看单个用户是在线还是离线状态。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{username}/status
路径参数

参数及说明详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户的在线状态数据。格式为:"用户 ID": "当前在线状态",例如,user1 的在线和离线状态分别为 "user1": "online" 和 "user1": "offline"。

其他字段及说明详见 公共参数

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/status'
响应示例
{
  "action": "get",
  "uri": "https://XXXX/XXXX/XXXX/users/user1/status",
  "entities": [],
  "data": {
    "user1": "offline"
  },
  "timestamp": 1542601284531,
  "duration": 4,
  "count": 0
}

批量获取用户在线状态

批量查看用户是在线还是离线状态,单次请求最多可查看 100 个用户的在线状态。

该接口不对用户 ID 进行校验。若查询不存在的用户 ID 的状态,则返回的状态为 offline

HTTP 请求

POST https://{host}/{org_name}/{app_name}/users/batch/status
路径参数

参数及说明详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
usernamesArray要查询状态的用户 ID,每次最多能传 100 个

HTTP 响应

响应 body

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

字段类型描述
actionString执行的操作。在该响应中,该参数的值为 get batch user status,表示批量获取用户在线状态。
dataJSON Array查询的用户的在线状态,数据格式为:"用户 ID": "当前在线状态",例如,user1 的在线和离线状态分别为 "user1": "online" 和 "user1": "offline"。

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

示例

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

curl -X POST https://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
}

获取指定账号的在线登录设备列表

多设备登录情况下,你可以调用该接口获取指定账号的在线登录设备列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{username}/resources

路径参数

参数类型是否必需描述
usernameString用户 ID。

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

请求 header

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

HTTP 响应

响应 body

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

参数类型描述
dataJSON Array已登录设备的列表。
- resString已登录设备的资源 ID,即服务器分配给每个设备资源的唯一标识符。资源 ID 的格式为 {device type}_{resource ID},其中设备类型 device type 可以是 androidioswebresource ID 由 SDK 分配。例如,android_123423453246
- device_uuidString已登录设备的 UUID。
- device_nameString已登录设备的名称。

其他参数及说明详见 公共参数

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl --location 'http://XXXX/XXXX/XXXX/users/XXXX/resources' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

{
    "path": "/users/XXXX/resources",
    "uri": "https://XXXX/XXXX/XXXX/users/XXXX/resources",
    "timestamp": 1692325141777,
    "organization": "XXXX",
    "application": "0XXXX4",
    "entities": [],
    "action": "get",
    "data": [
        {
            "res": "android_XXXX",
            "device_uuid": "2a54-XXXX",
            "device_name": "HUAWEI-XXXX"
        }
    ],
    "duration": 0,
    "applicationName": "chatdemoui"
}

用户全局禁言

随着监管机制日益完善,对 app 的监管不断加强,安全合规逐渐成为 app 的生命线。

为加强 app 管理,环信即时通讯提供全局禁言功能,对 app 提供用户 ID 级别的禁言管理,支持在管理员发现用户违规后进行全局禁言,以维护 app 良好的内容生态环境。禁言到期后,服务器会自动解除禁言,恢复该用户发送消息的权限。

你可以对单个用户 ID 设置单聊、群组或聊天室消息全局禁言。禁言后,该用户无论通过调用客户端 API,还是使用服务端 RESTful API 都将无法在对应的单聊、群组或聊天室发送消息。

该功能可广泛用于实时互动 app 中,例如发现某用户频繁向多个聊天室发送违规广告,则可以对该用户开启全局聊天室禁言 15 天;发现某用户发表触犯红线的政治言论,则可以全局永久禁言,用户申诉通过后可以解禁。

使用该功能前,你需先查看你的 IM 套餐版本是否开通了该功能。该功能与 IM 套餐包版本之间的开通关系,详见产品计费

设置用户全局禁言

设置单个用户 ID 的单聊、群组或聊天室消息的全局禁言。设置成功后,该用户将无法在对应的单聊、群组或聊天室中发送消息。

HTTP 请求

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

参数及说明详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
usernameString设置全局禁言的用户 ID。
chatInt单聊禁言时长,单位为秒,最大值为 2147483647
- > 0:该用户 ID 的单聊禁言时长。
- 0:取消该用户的单聊禁言。
- -1:该用户被设置永久单聊禁言。
- 其他负值无效。
groupchatInt群组禁言时长,单位为秒,规则同单聊禁言。
chatroomInt聊天室禁言时长,单位为秒,规则同单聊禁言。

HTTP 响应

响应 body

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

字段类型描述
data.resultString是否成功设置用户全局禁言。ok 表示设置成功。

其他字段及说明详见 公共参数

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

示例

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

curl -L -X POST 'https://XXXX/XXXX/XXXX/mutes' \
-H 'Authorization: Bearer <YourAppToken>' \
-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}/{org_name}/{app_name}/mutes/{username}
路径参数

参数及说明详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
data.useridString设置禁言的用户 ID。
data.chatInt单聊剩余禁言时间,单位为秒。最大值为 2147483647
- > 0:该用户 ID 剩余的单聊禁言时长。
- 0:该用户的单聊消息禁言已取消。
- -1:该用户被设置永久单聊消息禁言。
data.groupchatInt群组消息剩余禁言时长,单位为秒,规则同单聊禁言。
data.chatroomInt聊天室消息剩余禁言时长,单位为秒,规则同单聊禁言。
data.unixtimeInt当前操作的 Unix 时间戳。

其他字段及说明详见 公共参数

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

示例

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

curl -L -X GET 'https://XXXX/XXXX/XXXX/mutes/zs1' \
-H 'Authorization: Bearer <YourAppToken>' \
-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 请求

GET https://{host}/{org_name}/{app_name}/mutes
路径参数

参数及说明详见公共参数

查询参数
参数类型是否必需描述
pageNumInt请求查询的页码。
pageSizeInt请求查询每页显示的禁言用户的数量。取值范围为 [1,50]。
请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AuthorizationString鉴权 token,管理员 token(含)以上权限。

HTTP 响应

响应 body

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

字段类型描述
dataJSON Array获取的所有全局禁言的用户的信息。
- usernameString设置禁言的用户 ID。
- chatInt单聊消息剩余禁言时间,单位为秒。最大值为 2147483647
- > 0:该用户 ID 具体的单聊消息禁言时长。
- 0:该用户的单聊消息禁言已取消。
- -1:该用户被设置永久单聊消息禁言。
- groupchatInt群组消息剩余禁言时长,单位为秒,规则同上。
- chatroomInt聊天室消息剩余禁言时长,单位为秒,规则同上。
- unixtimeLong当前操作的 Unix 时间戳,单位为毫秒。

其他字段及说明详见 公共参数

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

示例

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

curl -L -X GET 'https://XXXX/XXXX/XXXX/mutes?pageNum=1&pageSize=10' \
-H 'Authorization: Bearer <YourAppToken>' \
-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_usernameString要获取离线消息数量的用户 ID。

其他参数及说明详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户的离线消息数量。数据格式为:"用户 ID": "当前离线消息的数量",例如,"user1": "0"。

其他字段及说明详见 公共参数

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/offline_msg_count'
响应示例
{
  "action": "get",
  "uri": "https://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}
路径参数
参数类型是否必需描述
usernameString要获取离线消息状态的用户 ID。
msg_idString要查看状态的离线消息 ID。

其他参数及说明详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON指定离线消息的投递状态。数据格式为 "消息 ID": "投递状态"。消息的投递状态有两种:
- delivered:已投递;
- undelivered:未投递。

其他字段及说明详见 公共参数

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123'
响应示例
{
  "action": "get",
  "uri": "https://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-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

参数类型描述
actionString执行的操作。在该响应中,该参数的值为 Deactivate user,表示对账号进行封禁。

其他字段及说明详见公共参数

如果返回的 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/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-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
actionString执行的操作。在该响应中,该参数的值为 activate user,表示对账号进行解禁。

其他字段及说明详见 公共参数

如果返回的 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/users/user1/activate'
响应示例
{
  "action": "activate user",
  "timestamp": 1542602404132,
  "duration": 9
}

强制用户下线

强制用户即将用户状态改为离线,用户需要重新登录才能正常使用。

多设备登录情况下,调用该接口会强制将指定用户从所有登录的设备下线;若将用户从指定设备上下线,你可以调用强制指定账号从单设备下线接口。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{username}/disconnect
路径参数

参数及说明详见 公共参数

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

HTTP 响应

响应 body

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

字段类型描述
data.resultBool用户是否已被强制下线:
- true:是;
- false:否。

其他字段及说明详见 公共参数

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

示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/disconnect'
响应示例
{
  "action": "get",
  "uri": "https://XXXX/XXXX/XXXX/users/user1/disconnect",
  "entities": [],
  "data": {
    "result": true
  },
  "timestamp": 1542602601332,
  "duration": 6,
  "count": 0
}

强制用户从单设备下线

如果用户在多个设备上登录,你可以调用该接口强制其在某一台设备上下线。若强制用户从所有设备下线,可以调用强制用户下线接口。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/users/{username}/disconnect/{resourceId}
路径参数
参数类型描述
usernameString要将哪个用户从指定设备下线。
resourceIdString要将用户从哪个设备下线,即用户已登录设备的资源 ID,即服务器分配给每个设备资源的唯一标识符。资源 ID 的格式为 {device type}_{resource ID},其中设备类型 device type 可以是 androidioswebresource ID 由 SDK 分配。例如,android_123423453246

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

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

HTTP 响应

响应 body

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

字段类型描述
resultBool用户是否已被强制从该设备下线:
- true:是;
- false:否。

如果返回的 HTTP 状态码非 200,表示请求失败。常见的错误为 404 错误,即用户不存在,如下所示:

{
    "error": "service_resource_not_found",
    "exception": "UserNotFoundException",
    "timestamp": 1709867821788,
    "duration": 0,
    "error_description": "Service resource not found"
}

关于其他异常,你可以参考 响应状态码 了解可能的原因。

示例

请求示例
<YourAppToken> 替换为你在服务端生成的 App Token 
curl -X DELETE -H 'Accept: application/json'   \
-H 'Authorization: Bearer <YourAppToken>' 'https://XXX/XXX/XXX/users/{userName}/disconnect/{resourceId}'
响应示例
{
    "uri": "https://XXX/XXX/XXX",
    "timestamp": 1709865422596,
    "organization": "XXX",
    "application": "6b58d05d-XXX-1ff3e95a3dc0",
    "entities": [],
    "action": "delete",
    "data": {
        "result": true
    },
    "duration": 0,
    "applicationName": "90"
}