用户体系集成

更新时间：2022-05-19

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

已在环信即时通讯控制台开通配置环信即时通讯 IM 服务。
已从服务端获取 app token，详见使用环信 app token 鉴权。

使用环信即时通讯 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，请重新发送正确数量的请求。

获取用户离线消息数量

获取 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	被限流或者发生异常。

用户体系集成

前提条件

接口概述

认证方式

用户管理具体接口

注册单个用户

接口描述

路径参数

请求头参数

请求体参数

响应体参数

请求示例

响应示例

响应码

批量注册用户

路径参数

请求体

响应体

请求示例

响应示例

请求示例2

响应示例

响应码

获取用户 token

HTTP 请求

路径参数

请求头参数

请求体参数

响应体参数

请求示例

响应示例

响应码

获取单个用户

基本信息

路径参数

请求参数

响应体

请求示例

响应示例

响应码

批量获取用户

基本信息

路径参数

请求参数

请求头

响应体参数

请求示例

响应示例

请求示例

响应示例

响应码

删除单个用户

基本信息

请求头

请求示例

响应示例

响应码

修改用户密码

基本信息

路径参数

请求头

请求体

请求示例

响应示例

响应码

批量删除用户

基本信息

请求头

请求示例

响应码

获取用户在线状态

基本信息

路径参数

请求头参数

响应参数

请求示例

响应示例

响应码

批量获取用户在线状态

基本信息