要调用环信即时通讯 RESTful API,请确保满足以下要求:
使用环信即时通讯 IM 前开发者须给用户创建用户 ID。
环信即时通讯 IM REST API 提供下文相应接口实现用户体系建立和管理。
不同接口有不同的流量限制,详见 使用限制。
以下为常出现的响应体参数及描述:
参数 | 描述 |
action | 请求方式,即接口方法名。 |
organization | 即 org_name ,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
application | 系统内为应用生成的唯一标识,开发者无需关心。 |
applicationName | 即 app_name ,你在环信即时通讯云控制台注册项目时填入的应用名称。 |
uri | 请求 URL。 |
path | 请求路径,属于请求 URL 的一部分,开发者无需关注。 |
entities | 详细信息。 |
data | 实际取到的数据详情。 |
uuid | 系统内为用户或者应用生成的系统内唯一标识,开发者无需关心。 |
created | 创建时间,Unix 时间戳,单位为毫秒。 |
username | 用户 ID,长度不可超过 64 个字节长度。不可设置为空。支持以下字符集:• 26 个小写英文字母 a-z; • 26 个大写英文字母 A-Z;• 10 个数字 0-9; • “_”, “-”, “.”。 注意: • 该参数不区分大小写,因此 Aa 和 aa 为相同用户名; • 请确保同一个 app 下,username 唯一; • username 用户 ID 是会公开的信息,请勿使用 UUID、邮箱地址、手机号等敏感信息。 |
groupname | 群组名。 |
timestamp | 请求响应时间,Unix 时间戳,单位为毫秒。 |
duration | 请求响应用时时长, 单位为毫秒。 |
环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式,详见 使用 Token 鉴权。
环信即时通讯 IM 提供多个接口实现用户的注册、获取、修改、删除、封禁、解禁、强制下线等管理功能。
名称 | 方法 | 请求 | 描述 |
注册单个用户 | POST | /{org_name}/{app_name}/users | 注册一个用户。 |
批量注册用户 | POST | /{org_name}/{app_name}/users | 注册多个用户。 |
获取用户 token | POST | /{org_name}/{app_name}/token | 获取用户 token。 |
获取单个用户 | GET | /{org_name}/{app_name}/users/{username} | 获取单个用户。 |
批量获取用户 | GET | /{org_name}/{app_name}/users | 获取应用下的多个用户。 |
删除单个用户 | DELETE | /{org_name}/{app_name}/users/{username} | 删除单个用户。 |
批量删除用户 | DELETE | /{org_name}/{app_name}/users | 批量删除多个用户。 |
修改用户密码 | POST | /{org_name}/{app_name}/users/{username}/password | 修改用户的密码。 |
获取用户在线状态 | GET | /{org_name}/{app_name}/users/{username}/status | 查看一个用户的在线状态。 |
批量获取用户在线状态 | POST | /{org_name}/{app_name}/users/batch/status | 批量查看用户的在线状态。 |
获取离线消息数 | GET | /{org_name}/{app_name}/users/{owner_username}/offline_msg_count | 获取一个 IM 用户的离线消息数。 |
获取离线消息的状态 | GET | /{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id} | 通过离线消息的 ID 查看用户的该条离线消息状态。 |
账号封禁 | POST | /{org_name}/{app_name}/users/{username}/deactivate | 禁用用户账号。 |
账号解禁 | POST | /{org_name}/{app_name}/users/{username}/activate | 解禁用户账号。 |
强制下线 | GET | /{org_name}/{app_name}/users/{username}/disconnect | 把用户状态改为离线。 |
注册单个用户
接口描述
在 URL 指定的 org_name
和 app_name
中创建一个新用户,需要授权注册模式。
WARNING:环信 ID 是会公开的信息,请不要使用手机号等敏感信息直接注册,需要映射后注册!!!
“授权注册”模式:注册 环信即时通讯 IM 账号时,必须携带管理员身份认证信息。推荐使用“授权注册”,这样可以防止某些已经获取了注册 URL 和知晓注册流程的人恶意向服务器大量注册垃圾用户。
方法:POST
接入点:https://{host}/{org_name}/{app_name}/users
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体参数
参数 | 类型 | 是否必需 | 说明 |
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;• 中文;• 特殊字符。 |
响应体参数
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户 ID。用户的唯一登录账号。 |
nickname | 昵称(可选),仅用在客户端推送通知栏显示的昵称,并不是用户个人信息的昵称,开发者可以自定义该内容。长度不可超过 100 个字符。 |
activated | 用户是否已激活。• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d '[
{
"username": "user1",
"password": "123",
"nickname": "testuser"
}
]' 'https://a1.easemob.com/easemob-demo/testapp/users'
响应示例
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/users",
"uri": "https://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b",
"type": "user",
"created": 1542795196504,
"modified": 1542795196504,
"username": "user1",
"activated": true,
"nickname": "testuser"
}
],
"timestamp": 1542795196515,
"duration": 0,
"organization": "easemob-demo",
"applicationName": "testapp"
}
响应码
响应码 | 意义 |
200 | 成功。 |
400 | 表示用户已存在、用户名或密码为空、用户名不合法。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429 | 被限流。 |
5xx | 被限流或者发生异常。 |
批量注册用户
批量注册是授权注册方式,服务端需要校验有效的 token 权限才能进行操作。每次调用接口时,注册用户数量有最大限制,详见 限制条件。
方法:POST
接入点:https://{host}/{org_name}/{app_name}/users
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
请求体
参数 | 类型 | 是否必需 | 说明 |
username | String | 必需 | 用户名,长度不可超过 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;• 中文;• 特殊字符。 |
响应体
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户名,也就是 环信用户 ID。 |
nickname | 昵称(可选),仅用在客户端推送通知栏显示的昵称,并不是用户个人信息的昵称,开发者可以自定义该内容。长度不可超过100个字符。支持以下字符集:• 26 个小写英文字母 a-z;• 26 个大写英文字母 A-Z;• 10 个数字 0-9;• 中文;• 特殊字符。 |
activated | 用户是否已激活:• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
请求示例
curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}]'
响应示例
{
"action": "post",
"application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d",
"path": "/users",
"uri": "https://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "278b5e60-e27b-11e8-8f9b-d5d83ebec806",
"type": "user",
"created": 1541587920710,
"modified": 1541587920710,
"username": "user1",
"activated": true,
"nickname": "testuser1"
},
{
"uuid": "278bac80-e27b-11e8-b192-73e4cd5078a5",
"type": "user",
"created": 1541587920712,
"modified": 1541587920712,
"username": "user2",
"activated": true,
"nickname": "testuser2"
} ],
"timestamp": 1541587920714,
"data": [],
"duration": 0,
"organization": "1122161011178276",
"applicationName": "testapp"
}
请求示例2
curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}, {"username":"user3", "password":"789","nickname":"testuser3"}]'
当请求 body 中存在已经注册过的 user 3 时,那么请求会成功并且 user 1、user 2 也会注册成功,response 中的 data 数组内是返回存在问题的用户。
响应示例
{
"action": "post",
"application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d",
"path": "/users",
"uri": "https://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "278b5e60-e27b-11e8-8f9b-d5d83ebec806",
"type": "user",
"created": 1541587920710,
"modified": 1541587920710,
"username": "user1",
"activated": true,
"nickname": "testuser1"
},
{
"uuid": "278bac80-e27b-11e8-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": "1122161011178276",
"applicationName": "testapp"}
响应码
响应码 | 意义 |
200 | 成功。 |
429 | 被限流。 |
5xx | 被限流或者发生异常。 |
获取用户 token
环信提供 2 种方式进行登录:
使用 “用户名” 和 “密码” 进行登录;
使用 ”用户名“ + ”用户Token“ 进行登录。
方式 1:在 SDK 进行登录时,使用 “用户名” 和 “密码” 进行登录。
该方式集成相对简单,用户注册后,直接使用 “用户名” 和 “密码” 进行登录。登录成功后,SDK 会获取一个长期的用户 token。
方式 2:开发者使用 RESTful API 在自己的应用服务器管理用户 token,在端上登录时,由应用服务器下发用户 token,SDK 使用用户名和用户 token 进行登录。
该方式开发者可以对用户 token 进行管理。获取用户 token 时,可以设置 token 有效期。
HTTP 请求
方法名:POST
接入点:https://{host}/{org_name}/{app_name}/token
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
请求体参数
参数 | 类型 | 是否必需 | 说明 |
grant_type | String | 必需 | password,密码。 |
username | String | 必需 | 用户名。 |
password | String | 必需 | 密码。 |
ttl | String | 必需 | token 有效期,单位为秒(s)。此外,也可通过环信即时通讯云控制台设置,参见 用户认证详情页面。该参数值以最新设置为准。 |
响应体参数
参数 | 类型 | 说明 |
access_token | String | 有效的用户 token 字符串。 |
expires_in | long | token 有效时间,以秒为单位,在有效期内不需要重复获取。 |
user | String | UUID :用户的 UUID、type :用户类型、created :创建时间(Unix 时间戳,单位为 ms)、modified :修改时间(Unix 时间戳,单位为 ms)、username :用户名、activated :是否激活(true :已激活;false :未激活)。 |
请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"grant_type": "password",
"username": "C",
"password": "1",
"ttl": "1024000"
}' 'http://a1.easemob.com/easemob-demo/testapp/token'
响应示例
返回值200,表示成功返回token
{
"access_token": "YWMtrR6ECkz8Eeyx6Y9j1eX9kbsMrFep3U6BvVj7KSnNonWqRx7gTPwR7Kzl-Q_xISNOAwMAAAF9UPZqbQAPoAAtYK9fWgaTNyuWoB3-6nGf_TXBx3Nt3XRZST-elU0x2A",
"expires_in": 1024000,
"user": {
"uuid": "aa471ee0-4cfc-11ec-ace5-f90ff121234e",
"type": "user",
"created": 1637740861395,
"modified": 1637740861395,
"username": "c",
"activated": true
}
}
响应码
响应码 | 意义 |
200 | 成功。 |
429,503 或者其他 5xx | 单位时间内请求过多。请稍后重试。 |
500 | 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。 |
获取单个用户
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/users/{username}
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必须 | 用户的用户名。 |
请求参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应体
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户名,也就是 环信用户 ID。 |
activated | 用户是否已激活• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
nickname | 昵称(可选),仅用在客户端推送通知栏显示的昵称,并不是用户个人信息的昵称,开发者可以自定义该内容。长度不可超过100个字符。支持以下字符集:• 26 个小写英文字母 a-z;• 26 个大写英文字母 A-Z;• 10 个数字 0-9;• 中文;• 特殊字符。 |
notification_display_style | 消息提醒方式,•“0”:仅通知;•“1“:通知以及消息详情,没有设置返不会返回。 |
notification_no_disturbing | 免打扰的设置。• true :免打扰开启,没有设置返不会返回。• false :代表免打扰关闭。 |
notification_no_disturbing_start | 免打扰的开始时间。数字代表开始时间,例如 “8” 代表每日 8:00 开启免打扰,没有设置则不会返回。 |
notification_no_disturbing_end \ | 免打扰的结束时间。数字代表结束时间,例如 “18” 代表每日 18:00 关闭免打扰,没有设置则不会返回。 |
notification_ignore_63112447328257 | 屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组 ID。• true :已屏蔽。• false :未屏蔽,没有设置则不会返回。 |
notifier_name | 客户端推送证书名称,没有设置则不会返回。 |
device_token | 推送 token,没有则不会返回。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1'
响应示例
{
"action": "get",
"path": "/users",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1",
"entities": [
{
"uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b",
"type": "user",
"created": 1542795196504,
"modified": 1542795196504,
"username": "user1",
"activated": true,
"nickname": "testuser"
} ],
"timestamp": 1542798985011,
"duration": 6,
"count": 1
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
批量获取用户
该接口默认返回按照创建时间排序,如果需要指定获取数量,需加上参数 limit = N,N 为数量值。关于分页:如果 DB 中的数量大于 N,返回 JSON 会携带一个字段 “cursor”,我们把它叫做”游标”,该游标可理解为结果集的指针,值是变化的。往下取数据的时候带着游标,就可以获取到下一页的值。如果还有下一页,响应码里依然还有这个字段,直到没有这个字段,说明已经到最后一页。cursor 的意义在于数据分页。
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/users?limit={N}&{cursor}
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
请求参数
参数 | 类型 | 是否必需 | 描述 |
limit | Int | 非必需 | 获取用户的数量。默认值 10,最大值 100。超过 100 按照 100 返回。 |
activated | Boolean | 非必需 | 用户是否激活。• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
cursor | String | 非必需 | 游标,用于分页显示用户列表。第一次发起批量查询用户请求时无需设置 cursor ,请求成功后会获得第一页用户列表。从响应 body 中获取 cursor ,并在下一次请求的 URL 中传入该 cursor ,直到响应 body 中不再有 cursor 字段,则表示已查询到 app 中所有用户。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应体参数
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户名,也就是 环信用户 ID。 |
nickname | 昵称(可选),仅用在客户端推送通知栏显示的昵称,并不是用户个人信息的昵称,开发者可以自定义该内容。长度不可超过 100 个字符。支持以下字符集:• 26 个小写英文字母 a-z;• 26 个大写英文字母 A-Z;• 10 个数字 0-9;• 中文;• 特殊字符。 |
activated | 用户是否已激活• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
notification_display_style | 消息提醒方式,•“0”:仅通知;•“1“:通知以及消息详情,没有设置返不会返回。 |
notification_no_disturbing | 免打扰的设置。“0” 代表免打扰关闭,“1” 免打扰开启,没有设置则不会返回。 |
notification_no_disturbing_start | 免打扰的开始时间。数字代表开始时间,例如 “8” 代表每日 8:00 开启免打扰,没有设置则不会返回。 |
notification_no_disturbing_end | 免打扰的结束时间。数字代表结束时间,例如 “18” 代表每日 18:00 关闭免打扰,没有设置则不会返回。 |
notification_ignore_63112447328257 | 屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组 ID。• true :已屏蔽。• false :未屏蔽,没有设置则不会返回。 |
notifier_name | 客户端推送证书名称,没有设置则不会返回。 |
device_token | 推送 token,没有则不会返回。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2'
使用返回的 cursor 获取下一页
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB'
响应示例
{
"action": "get",
"params":
{
"limit": [ "2" ]
},
"path": "/users",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "ab90eff0-e978-11e8-9174-8f161649a182",
"type": "user",
"created": 1542356511855,
"modified": 1542356511855,
"username": "user1",
"activated": true,
"nickname": "user1"
},
{
"uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
"type": "user",
"created": 1542356523769,
"modified": 1542356523769,
"username": "user2",
"activated": true,
"nickname": "user2"
} ],
"timestamp": 1542558467056,
"duration": 11,
"cursor": "LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB",
"count": 2
}
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB'
响应示例
{
"action": "get",
"params":
{
"cursor": [
"LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB"
],
"limit": [
"2" ]
},
"path": "/users",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "fef7f250-e983-11e8-ba39-0fed7dcc3cdd",
"type": "user",
"created": 1542361376245,
"modified": 1542361376245,
"username": "testuser",
"activated": true,
"nickname": "testuser"
} ],
"timestamp": 1542559337702,
"duration": 2,
"count": 1
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429 或者 5xx | 被限流或者发生异常。 |
删除单个用户
删除一个用户,如果此用户是群组或者聊天室的群主,系统会同时删除这些群组和聊天室。请在操作时进行确认。
基本信息
方法:DELETE
接入点:https://{host}/{org_name}/{app_name}/users/{username}
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 需要进行删除用户的用户名。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求示例
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users/user1'
响应示例
{
"action": "delete",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/users",
"uri": "https://a1.easemob.com/easemob-demo/testapp/users",
"entities": [
{
"uuid": "ab90eff0-e978-11e8-9174-8f161649a182",
"type": "user",
"created": 1542356511855,
"modified": 1542356511855,
"username": "user1",
"activated": true,
"nickname": "user1"
} ],
"timestamp": 1542559539776,
"duration": 39,
"organization": "easemob-demo",
"applicationName": "testapp"
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
修改用户密码
可以通过服务端接口修改用户的登录密码,不需要提供原密码。
基本信息
方法:PUT
接入点:https://{host}/{org_name}/{app_name}/users/{username}/password
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 用户的用户名。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体
参数 | 说明 |
newpassword | ${新密码指定的字符串} |
请求示例
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{ "newpassword": "123" }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/password'
响应示例
{
"action": "set user password",
"timestamp": 1542595598924,
"duration": 8}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
批量删除用户
删除某个 APP 下指定数量的用户账号。可一次删除 N 个用户,数值可以修改。建议这个数值在 100 以内,不要过大。需要注意的是,这里只是批量的一次性删除掉 N 个用户,具体删除哪些并没有指定,可以在返回值中查看到哪些用户被删除掉了。
基本信息
方法:DELETE
接入点:https://{host}/{org_name}/{app_name}/users
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求示例
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2'
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
429 或者 5xx | 被限流或者发生异常。 |
获取用户在线状态
基本信息
方法名:GET
接入点:https://{host}/{org_name}/{app_name}/users/{username}/status
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 | |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 用户名(用户 ID)。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应参数
参数 | 说明 |
username | 数据格式为:“用户名:当前在线状态”,例如,user1 的在线和离线状态分别为 “user1”: “online” 和”user1”: “offline”。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/status'
响应示例
{
"action": "get",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/status",
"entities": [],
"data": {
"user1": "offline"
},
"timestamp": 1542601284531,
"duration": 4,
"count": 0
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
批量获取用户在线状态
批量查看用户的在线状态,最多可同时查看 100 个用户的状态。
基本信息
方法:POST
接入点:https://{host}{org_name}/{app_name}/users/batch/status
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 | |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体参数
参数 | 说明 |
usernames | 要查询状态的用户名,以数组方式提交,最多不能超过 100 个。 |
响应参数
参数 | 说明 |
username | 数据格式为:“用户名:当前在线状态”,例如,user1 的在线和离线状态分别为 “user1”: “online” 和”user1”: “offline”。 |
请求示例
curl -X POST http://a1.easemob.com/easemob-demo/chatdemoui/users/batch/status -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'Content-Type: application/json' -d '{"usernames":["user1","user2"]}'
响应示例
该接口不对用户名进行校验。若查询不存在的用户名的状态,则返回的状态为 offline。
{
"action": "get batch user status",
"data": [
{
"user1": "offline"
},
{
"user2": "offline"
}
],
"timestamp": 1552280231926,
"duration": 4
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流、发生异常或者单次请求的用户数大于 100,请重新发送正确数量的请求。 |
获取用户离线消息数量
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/offline_msg_count
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 | |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
owner_username | String | 必需 | 要获取离线消息数的用户名(用户 ID)。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应参数
参数 | 说明 |
username | 数据格式为:“用户名:当前离线消息的数量“,例如,”user1: 0”。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_count'
响应示例
{
"action": "get",
"uri": "http://tomcatcluster_users/easemob-demo/testapp/users/user1/offline_msg_count",
"entities": [],
"data": {
"user1": 0
},
"timestamp": 1542601518137,
"duration": 3,
"count": 0
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
获取某条离线消息状态
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 | |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 要获取离线消息状态的用户名(用户 ID)。 |
msg_id | String | 必需 | 要查看离线消息状态的 ID。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应参数
参数 | 说明 |
msg_id | 数据格式为“消息 ID”:“离线状态”。消息的离线状态有两种: “delivered” 表示已投递,`undelivered“ 表示未投递。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_status/123'
响应示例
{
"action": "get",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_status/123",
"entities": [],
"data": {
"123": "delivered"
},
"timestamp": 1542601830084,
"duration": 5,
"count": 0
}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
账号封禁
环信即时通讯 IM 提供了对用户的禁用以及解禁接口操作,用户若被禁用将立即下线并无法登录进入环信即时通讯 IM,直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。
基本信息
方法:POST
接入点:https://{host}/{org_name}/{app_name}/users/{username}/deactivate
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 用户名。 |
响应体
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户名,也就是环信用户 ID。 |
activated | 用户是否已激活• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/deactivate'
响应示例
{
"action": "Deactivate user",
"entities": [
{
"uuid": "4759aa70-eba5-11e8-925f-6fa0510823ba",
"type": "user",
"created": 1542595573399,
"modified": 1542597578147,
"username": "user1",
"activated": false,
"nickname": "user"
} ],
"timestamp": 1542602157258,
"duration": 12}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
400 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
账号解禁
环信即时通讯 IM 提供了对用户的禁用以及解禁接口操作,对用户禁用用户将立即下线并无法登录进入环信即时通讯 IM,直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。
基本信息
方法:POST
接入点:https://{host}/{org_name}/{app_name}/users/{username}/activate
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
路径参数
参数 | 类型 | 是否必需 | 描述 |
host | String | 必需 | 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在环信即时通讯云控制台注册项目时填入的应用名称。 |
username | String | 必需 | 用户 ID。 |
响应体
参数 | 说明 |
uuid | 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。 |
type | “user” 用户类型。 |
username | 用户名,也就是环信用户 ID。 |
activated | 用户是否已激活• true :已激活。• false :封禁,封禁需要通过解禁接口进行解禁,才能正常登录。 |
请求示例
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/activate'
响应示例
{
"action": "activate user",
"timestamp": 1542602404132,
"duration": 9}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |
强制下线
强制用户即把用户状态改为离线,用户需要重新登录才能正常使用。
基本信息
方法:GET
接入点:https://{host}/{org_name}/{app_name}/users/{username}/disconnect
请求头
参数 | 类型 | 是否必需 | 描述 |
Content-Type | String | 必需 | 内容类型:application/json |
Authorization | String | 必需 | Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
响应体
参数 | 说明 |
result | 操作结果,“true” 表示用户已经被强制下线。 |
请求示例
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect'
响应示例
{
"action": "get",
"uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect",
"entities": [],
]"data": {
"result": true
},
"timestamp": 1542602601332,
"duration": 6,
"count": 0}
响应码
响应码 | 意义 |
200 | 成功。 |
401 | 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。 |
404 | 用户不存在。 |
429 或者 5xx | 被限流或者发生异常。 |