用户体系集成

更新时间:2022-05-19

要调用环信即时通讯 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;
• “_”, “-”, “.”。
注意:
• 该参数不区分大小写,因此 Aaaa 为相同用户名;
• 请确保同一个 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_nameapp_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;
• “_”, “-”, “.”。
注意:
• 该参数不区分大小写,因此 Aaaa 为相同用户名;
• 请确保同一个 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;
• “_”, “-”, “.”。
注意:
• 该参数不区分大小写,因此 Aaaa 为相同用户名;
• 请确保同一个 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 种方式进行登录:

  1. 使用 “用户名” 和 “密码” 进行登录;
  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,请重新发送正确数量的请求。

获取用户离线消息数量

获取 IM 用户的离线消息数量。

基本信息

方法: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 被限流或者发生异常。