更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。

新版文档见：用户体系集成。

介绍 AppKey 和环信 ID 的数据结构以及使用规则。

当您申请了 AppKey 后，会得到一个 xxxx#xxxx 格式的字符串，字符串只能由小写字母数字组成，AppKey 是环信应用的唯一标识。前半部分 org_name 是在多租户体系下的唯一租户标识，后半部分 app_name 是租户下的 App 唯一标识（在环信后台创建一个 App 时填写的应用 ID 即是 app_name ）。下述的 REST API 中，/{org_name}/{app_name} 的请求，均是针对一个唯一的 AppKey 进行的。目前环信注册的 AppKey 暂不能由用户自己完成删除操作，如果对 APP 删除需要联系环信操作完成。

环信作为一个聊天通道，只需要提供环信 ID （也就是 IM 用户名）和密码就够了。

当 APP 和环信集成的时候，需要把 APP 系统内的已有用户和新注册的用户和环信集成，为每个已有用户创建一个环信的账号（环信 ID），并且 APP 有新用户注册的时候，需要同步的在环信中注册。

在注册环信账户的时候，需要注意环信 ID 的规则：

• 使用英文字母和（或）数字的组合
• 不能使用中文
• 不能使用 email 地址
• 不能使用 UUID
• 用户 ID 的长度在 64 字节以内
• 中间不能有空格或者井号（#）等特殊字符
• 允许的用户名正则 “[a-z0-9_-.]*”（a~z小写字母/数字/下划线/横线/英文句号），其他都不允许 如果是大写字母会自动转成小写
• 不区分大小写。系统忽略大小写，认为 AA、Aa、aa、aA 都是一样的。如果系统已经存在了环信 ID 为 AA 的用户，再试图使用 aa 作为环信 ID 注册新用户，系统返回用户名重复，以此类推, 因此建议用户使用小写字母，否则可能遇到一些异常情况。但是请注意：环信 ID 在数据上的表现形式还是用户最初注册的形式，注册时候使用的大写就保存大写，是小写就保存小写。即：使用 AA 注册，环信保存的 ID 就是 AA；使用 Aa 注册，环信保存的 ID 就是 Aa，以此类推。

另：本文档中可能会交错使用“环信 ID”和“环信用户名”两个术语，但是请注意，这里两个的意思是一样的。

因为一个用户的环信 ID 和他的在 APP 中的用户名并不需要一致，只需要有一个明确的对应关系。例如，用户名是 example@easemob.com，当这个用户登录到 APP 的时候，可以登录成功之后，再登录环信的服务器，所以这时候，只需要能够从 example@easemob.com 推导出这个用户的环信 ID 即可。

注意：以下所有 API 均需要 org 管理员或 APP 管理员权限才能访问。

强烈建议保护好 org 管理员，APP 管理员的用户名和密码以及 APP 的 client_id 和 client_secret，尽量只在 APP 的服务器后台对环信用户做增删改查的管理，包括新用户注册。为了您的信息安全，请一定不要将 org 管理员或 APP 管理员的用户名和密码写死在手机客户端中，因为手机 APP 很容易被反编译，从而导致别人获取到您的管理员账号和密码，导致数据泄露。

介绍关于 IM 用户体系集成过程中，需要使用到的 REST API 文档详细说明，可以通过使用文档中嵌入的Easemob REST API进行在线测试。

环信不同数据中心的REST API请求域名：

应用所在数据中心可以在环信用户管理后台>应用列表找到对应的appkey点击“查看”>即时通讯>服务概览中查看：

注意：

1.为满足不同客户的业务需求，环信在多地部署了数据中心。不同数据中心的 REST API 请求域名不同。请根据您所在数据中心选择请求域名。

2.国内 VIP 区、客服专区客户请联系商务经理索要 REST API 请求地址。

3.支持 HTTP 和 HTTPS。

环信提供的 REST API 需要权限才能访问，权限通过发送 HTTP 请求时携带 token 来体现，下面描述获取 token 的方式。说明：API 描述的时候使用到的 {APP 的 client_id} 之类的这种参数需要替换成具体的值。

重要提醒： 获取 token 时服务器会返回 token 有效期，具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因，系统不保证 token 在此值表示的有效期内绝对有效，如果发现 token 使用异常请重新获取新的 token，比如“http response code”返回 401。另外，请不要频繁向服务器发送获取 token 的请求，同一账号发送此请求超过一定频率会被服务器封号，切记，切记！！

client_id 和 client_secret 可以在环信管理后台的 APP 详情页面看到。

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{ 
   "grant_type": "client_credentials",  
   "client_id": "YXA6i-Ak8Ol4Eei2l11ZjV-EAg", 
   "client_secret": "YXA6VunqiNxoB7IwXHInk1cGiXOOJfc",
   "ttl": "1024000"
 }' 'http://a1.easemob.com/easemob-demo/testapp/token'

返回值200，表示成功返回token

{
  "access_token": "YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw",
  "expires_in": 5184000,
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402"
}

返回值400，表示 client_id 或 client_secret 错误

{
  "access_token": "YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw",
  "expires_in": 1024000,
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

环信提供多个接口实现对 IM 用户的注册、获取、修改、删除等管理功能。

在 URL 指定的 org 和 APP 中创建一个新的用户，分两种模式：开放注册和授权注册。

• “开放注册”模式：注册环信账号时，不用携带管理员身份认证信息；
• “授权注册”模式：注册环信账号时，必须携带管理员身份认证信息。推荐使用“授权注册”，这样可以防止某些已经获取了注册 URL 和知晓注册流程的人恶意向服务器大量注册垃圾用户。

注意：

• 以下 API 中提到的 ${token} 是个变量，使用时需要替换成通过 APP 的 client_id 和 client_secret 获取到的 token。

• 在注册环信 id 时，建议不要使用有序的 id 进行注册，防止其他人知道注册 id 的顺序，恶意发送大量的垃圾消息。

• 服务器端给自己用户注册账号的同时，在调用环信的rest接口给用户在注册一个环信id与自己的用户绑定，并返回给客户端，客户端拿到自己服务器用户的账号密码登录后，在拿环信id密码在登录环信服务器。

用户可以在登录客户端 SDK 后自行通过账号密码注册账号的接口。

在返回值中查看entities字段包含的信息

curl -X POST -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '{"username":"user1","password":"123","nickname":"testuser"}'

返回值200，表示创建 IM 用户成功

{
  "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"
}

返回值400，表示用户已存在、用户名或密码为空、用户名不合法

{
  "error": "duplicate_unique_property_exists",
  "timestamp": 1542795141631,
  "duration": 0,
  "exception": "org.apache.usergrid.persistence.exceptions.DuplicateUniquePropertyExistsException",
  "error_description": "Application null Entity user requires that property named username be unique, value of User1 exists"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

服务端需要校验有效的token权限才能进行操作，授权注册的接口。

在返回值中查看entities字段包含的信息

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d '[  
   {  
     "username": "user1",  
     "password": "123",  
     "nickname": "testuser"  
   }  
 ]' 'http://a1.easemob.com/easemob-demo/testapp/users'

返回值200，表示创建 IM 用户成功

{
    "action": "post",
    "application": "a2e433a0-ab1a-11e2-a134-85fca932f094",
    "params": {},
    "path": "/users",
    "uri": "https://a1.easemob.com/easemob-demo/testapp/users",
    "entities": [{
        "uuid": "7f90f7ca-bb24-11e2-b2d0-6d8e359945e4",
        "type": "user",
        "created": 1368377620796,
        "modified": 1368377620796,
        "username": "user1",
        "activated": true
        "nickname": "testuser"
    }],
    "timestamp": 1368377620793,
    "duration": 125,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

返回值400，表示用户已存在、用户名或密码为空、用户名不合法

{
    "error": "duplicate_unique_property_exists",
    "timestamp": 1537871738097,
    "duration": 0,
    "exception": "org.apache.usergrid.persistence.exceptions.DuplicateUniquePropertyExistsException",
    "error_description": "Application null Entity user requires that property named username be unique, value of ccccc1 exists"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "auth_bad_access_token",
  "timestamp": 1543479294349,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

批量注册是授权注册方式，服务端需要校验有效的token权限才能进行操作。每次调用接口时，注册用户数量有最大限制，详见接口限流说明。

在返回值中查看entities字段包含的信息

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"}]'

返回值200，表示成功返回token

{
  "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"
}

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 中存在已经注册过的 user3 时，那么请求会成功并且user1、user2也会注册成功，response 中的 data 数组内是返回存在问题的用户。

返回值200，表示成功返回token

{
  "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"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

环信提供2种方式进行登录：1.使用“用户名”和“密码”进行登录；2.使用”用户名“+”用户Token“进行登录

方式1:在SDK进行登录时，使用“用户名”和“密码”进行登录。

该方式集成相对简单，用户注册后，直接使用“用户名”和“密码”进行登录。登录成功后，SDK会获取一个长期的用户token。

方式2:开发者使用RESTful API在自己的应用服务器管理用户token，在端上登录时，由应用服务器下发用户token，SDK使用用户名和用户token进行登录。

该方式开发者可以对用户token进行管理。获取用户token时，可以设置token有效期。

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
    }
}

返回值400，表示 username 或 password 错误

{
    "error": "invalid_grant",
    "timestamp": 1637741269908,
    "duration": 0,
    "error_description": "invalid password"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取单个 IM 用户的详细信息接口。

	/{org_name}/{app_name}/users/{username}

需要在请求时对应填写{username}，需要获取的 IM 用户名。

在返回值中查看entities字段包含的信息

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1'

返回值200，表示获取用户信息成功

{
  "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
}

返回值404，表示该用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542799099701,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542799184277,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/b2aade90-e978-11e8-a974-f3368f82e4f1]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

该接口默认返回按照创建时间排序，如果需要指定获取数量，需加上参数 limit=N，N 为数量值。关于分页：如果 DB 中的数量大于 N，返回 JSON 会携带一个字段“cursor”,我们把它叫做”游标”，该游标可理解为结果集的指针，值是变化的。往下取数据的时候带着游标，就可以获取到下一页的值。如果还有下一页，返回值里依然还有这个字段，直到没有这个字段，说明已经到最后一页。cursor的意义在于数据（真）分页。

	/{org_name}/{app_name}/users

需要在请求时对应填写{username}，需要获取的 IM 用户名。

在返回值中查看entities字段包含的信息

不分页

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'

返回值200，表示获取用户信息成功

{
  "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
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542559172189,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

分页

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB'

返回值200，表示获取用户信息成功

{
  "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
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542559373319,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

删除一个用户，如果此用户是群组或者聊天室的群主owner，系统会同时删除这些群组和聊天室。请在操作时进行确认。

	/{org_name}/{app_name}/users/{username}

需要在请求时对应填写{username}，需要删除的 IM 用户名。

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users/user1'

返回值200，表示用户删除成功

{
  "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"
}

返回值404，表示该用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542559595134,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "service_resource_not_found",
  "timestamp": 1542559595134,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

删除某个 APP 下指定数量的环信账号。可一次删除 N 个用户，数值可以修改。建议这个数值在100-500之间，不要过大。需要注意的是，这里只是批量的一次性删除掉 N个用户，具体删除哪些并没有指定，可以在返回值中查看到哪些用户被删除掉了。

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2'

返回值200，表示用户删除成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "params": {
    "limit": [
      "2"
    ]
  },
  "path": "/users",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    },
    {
      "uuid": "b98ad170-e978-11e8-8fce-7f76daa76557",
      "type": "user",
      "created": 1542356535303,
      "modified": 1542356535303,
      "username": "user3",
      "activated": true,
      "nickname": "user3"
    }
  ],
  "timestamp": 1542867197779,
  "duration": 504,
  "organization": "easemob-demo",
  "applicationName": "testapp",
  "cursor": "LTgzNDAxMjM3OTpfdmZ5VU9tREVlaTZPUV90ZmN3ODNR"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542867266449,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

可以通过服务端接口修改 IM 用户的登录密码，不需要提供原密码。

	/{org_name}/{app_name}/users/{username}/password

需要在请求时对应填写{username}，需要修改密码的 IM 用户名。

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'

返回值200，表示用户密码修改成功

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

返回值404，表示该用户不存在

{
  "error": "entity_not_found",
  "timestamp": 1542595648340,
  "duration": 0,
  "exception": "org.apache.usergrid.persistence.exceptions.EntityNotFoundException",
  "error_description": "User null not found"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

设置用户的推送昵称，在离线推送时使用。

	/{org_name}/{app_name}/users/{username}

需要在请求时对应填写{username}，需要修改推送昵称的 IM 用户名。

在返回值中查看entities字段包含的信息

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{ 
   "nickname": "testuser"  
 }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1'

返回值200，表示用户推送昵称修改成功

{
  "action": "put",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users",
  "entities": [
    {
      "uuid": "4759aa70-eba5-11e8-925f-6fa0510823ba",
      "type": "user",
      "created": 1542595573399,
      "modified": 1542596083687,
      "username": "user1",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542596083685,
  "duration": 6,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值400，表示该用户不存在

{
  "error": "required_property_not_found",
  "timestamp": 1542597341919,
  "duration": 0,
  "exception": "org.apache.usergrid.persistence.exceptions.RequiredPropertyNotFoundException",
  "error_description": "Entity user requires a property named username"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542597533232,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:put:8be024f0-e978-11e8-b697-5d598d5f8402:/users]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

设置推送消息至客户端的方式，修改后及时有效。服务端对应不同的设置，向用户发送不同展示方式的消息。

	/{org_name}/{app_name}/users/{username}

需要在请求时对应填写{username}，需要推送的 IM 用户名。

在返回值中查看entities字段包含的信息

curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  https://a1.easemob.com/easemob-demo/testapp/users/a -d '{"notification_display_style": "1"}'

返回值200，表示修改成功

{
  "action" : "put",
  "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99",
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/testapp/users",
  "entities" : [ {
    "uuid" : "3b8c9890-7b9a-11e8-9d88-f50bf55cafad",
    "type" : "user",
    "created" : 1530276298905,
    "modified" : 1534407146060,
    "username" : "user1",
    "activated" : true,
    "notification_no_disturbing" : false,
    "notification_no_disturbing_start" : 1,
    "notification_no_disturbing_end" : 3,
    "notification_display_style" : 1,
    "nickname" : "testuser",
    "notifier_name" : "2882303761517426801"
  } ],
  "timestamp" : 1534407146058,
  "duration" : 3,
  "organization" : "1112171214115068",
  "applicationName" : "testapp"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明 使用 Easemob REST API 在线测试

设置 IM 用户免打扰，在免打扰期间，用户将不会收到离线消息推送。

	/{org_name}/{app_name}/users/{username}

需要在请求时对应填写{username}，需要设置免打扰的 IM 用户名

在返回值中查看entities字段包含的信息

设置免打扰时间

curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  "https://a1.easemob.com/easemob-demo/testapp/users/a " -d '{"notification_no_disturbing": true,"notification_no_disturbing_start": "1","notification_no_disturbing_end": "3"}'

取消免打扰

curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  "https://a1.easemob.com/easemob-demo/testapp/users/a " -d '{"notification_no_disturbing": false}'

返回值200，表示设置成功

{
  "action" : "put",
  "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99",
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/testapp/users",
  "entities" : [ {
    "uuid" : "3b8c9890-7b9a-11e8-9d88-f50bf55cafad",
    "type" : "user",
    "created" : 1530276298905,
    "modified" : 1534405429835,
    "username" : "User1",
    "activated" : true,
    "notification_no_disturbing" : true,
    "notification_no_disturbing_start" : 1,
    "notification_no_disturbing_end" : 3,
    "notification_display_style" : 0,
    "nickname" : "testuser",
    "notifier_name" : "2882303761517426801"
  } ],
  "timestamp" : 1534405429833,
  "duration" : 4,
  "organization" : "1112171214115068",
  "applicationName" : "testapp"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

环信提供多个接口实现对 IM 用户的好友以及黑名单进行添加和移除。

添加好友，好友必须是和自己在一个 APPkey 下的 IM 用户，单用户ID可以添加的好友数量，请参考不同版本数量

	/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

需要在请求时对应填写{owner_username}，要添加好友的用户名，以及{friend_username}，好友用户名。

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/contacts/users/user2'

返回值200，表示添加好友成功

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542598913819,
  "duration": 63,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示此IM用户或被添加的好友不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542598965722,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，未授权[无token、token错误、token过期]

{
  "error": "auth_bad_access_token",
  "timestamp": 1542599042628,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

从 IM 用户的好友列表中移除一个 IM 用户。

	/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

需要在请求时对应填写{owner_username}，要删除好友的用户名，以及{friend_username}，被删除好友的用户名。

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users/user2'

返回值200，表示好友删除成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542599266616,
  "duration": 350,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示此IM用户或被删除的好友不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542599413796,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542599447198,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取 IM 用户的好友列表。

	/{org_name}/{app_name}/users/{owner_username}/contacts/users

需要在请求时对应填写{owner_username}，获取好友列表的用户名

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users'

返回值200，表示查看好友成功

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users",
  "entities": [],
  "data": [
    "user3",
    "user2"
  ],
  "timestamp": 1543819826513,
  "duration": 12,
  "count": 2
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542599741965,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542599778401,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取 IM 用户的黑名单。

	/{org_name}/{app_name}/users/{owner_username}/blocks/users

需要在请求时对应填写{owner_username}，获取黑名单的用户名

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users'

返回值200，表示查看用户黑名单成功

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users",
  "entities": [],
  "data": [
    "user2"
  ],
  "timestamp": 1542599978751,
  "duration": 4,
  "count": 1
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542600037889,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542600068826,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

向 IM 用户的黑名单列表中添加一个或者多个用户，黑名单中的用户无法给该 IM 用户发送消息，每个用户的黑名单人数上限为500。

	/{org_name}/{app_name}/users/{owner_username}/blocks/users

需要在请求时对应填写{owner_username}，要添加黑名单的用户名

在返回值中查看data字段包含的信息

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{  
   "usernames": [  
     "user2"  
   ]  
 }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users'

返回值200，表示添加黑名单成功

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "https://a1.easemob.com/easemob-demo/testapp",
  "entities": [],
  "data": [
    "user2"
  ],
  "timestamp": 1542600372046,
  "duration": 11,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542600419231,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值400，表示被添加的用户不存在

{
  "error": "illegal_argument",
  "timestamp": 1542600449246,
  "duration": 0,
  "exception": "java.lang.IllegalArgumentException",
  "error_description": "attempt to adding new block[user20] for user[user1],but user[user20] not found."
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542600528822,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:post:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

从 IM 用户的黑名单中移除用户。将用户从黑名单移除后，恢复到好友，或者未添加好友的用户关系。可以正常的进行消息收发。

	/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}

需要在请求时对应填写{owner_username}，要移除黑名单的用户名

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users/user2'

返回值200，表示移出黑名单成功

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542600712985,
  "duration": 20,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

返回值404，表示此IM用户或被减的用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542600858000,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542600910575,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

环信提供多个接口，可以查看用户的在线/离线状态，用户的消息的在线/离线状态和数量。

查看一个用户的在线状态。

	/{org_name}/{app_name}/users/{username}/status

需要在请求时对应填写{username}，要获取在线状态的用户名。

在返回值中查看data字段包含的信息

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/status'

返回值200，表示查询用户状态成功

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/status",
  "entities": [],
  "data": {
    "user1": "offline"
  },
  "timestamp": 1542601284531,
  "duration": 4,
  "count": 0
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542601345042,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542601375113,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

批量查看用户的在线状态，最大同时查看100个用户。

在返回值中查看data字段包含的信息

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"]}'

返回值200，表示查询用户状态成功

如果请求输入错误的用户名，即请求不存在的用户状态，则返回的参数一定是offline，此接口不对用户名进行校验。

{
    "action": "get batch user status",
    "data": [
        {
            "user1": "offline"
        },
        {
            "user2": "offline"
        }
    ],
    "timestamp": 1552280231926,
    "duration": 4
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542601375113,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试；或者或者请求的用户数大于100，请重新发送正确数量的请求。详见接口限流说明

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

	/{org_name}/{app_name}/users/{owner_username}/offline_msg_count

需要在请求时对应填写{owner_username}，要获取离线消息数的用户名。

在返回值中查看data字段包含的信息

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_count'

返回值200，表示查询离线消息数成功

{
  "action": "get",
  "uri": "http://tomcatcluster_users/easemob-demo/testapp/users/user1/offline_msg_count",
  "entities": [],
  "data": {
    "user1": 0
  },
  "timestamp": 1542601518137,
  "duration": 3,
  "count": 0
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542601576537,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542601604510,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取 IM 用户的离线消息状态，查看用户的离线消息离线消息的状态

	/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}

需要在请求时对应填写{username}，要获取离线消息状态的用户名。{msg_id}，要查看离线消息状态的ID。

在返回值中查看data字段包含的信息

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'

返回值200，表示查询离线消息状态成功

{
  "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
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542601878917,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542601903781,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

环信提供了对 IM 用户的禁用以及解禁接口操作，对用户禁用用户将立即下线并无法登录进入环信，直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。

禁用某个 IM 用户的账号，禁用后该用户不可登录，下次解禁后该账户恢复正常使用。

	/{org_name}/{app_name}/users/{username}/deactivate

需要在请求时对应填写{username}，要禁用的用户名。

在返回值中查看entities字段包含的信息

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'

返回值200，表示禁用用户账号成功

{
  "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
}

返回值400，表示此IM用户不存在

{
  "error": "management",
  "timestamp": 1542602213887,
  "duration": 0,
  "exception": "org.apache.usergrid.management.exceptions.ManagementException",
  "error_description": "User with id null does not exist in app 8be024f0-e978-11e8-b697-5d598d5f8402"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542602239851,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "No admin user access authorized"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

解除 IM 用户账号的禁用操作，由禁用到解禁操作后，需要用户重新登录。

	/{org_name}/{app_name}/users/{username}/activate

需要在请求时对应填写{username}，要解禁的用户名。

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'

返回值200，表示用户账号解禁成功

{
  "action": "activate user",
  "timestamp": 1542602404132,
  "duration": 9
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542602447129,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542602487688,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "No admin user access authorized"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

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

	/{org_name}/{app_name}/users/{username}/disconnect

需要在请求时对应填写{username}，要强制下线的用户名。

在返回值中查看data字段包含的信息

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect'

返回值200，表示强制用户下线成功

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect",
  "entities": [],
  "data": {
    "result": true
  },
  "timestamp": 1542602601332,
  "duration": 6,
  "count": 0
}

返回值404，表示此IM用户不存在

{
  "error": "service_resource_not_found",
  "timestamp": 1542602640827,
  "duration": 0,
  "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException",
  "error_description": "Service resource not found"
}

返回值401，表示未授权[无token、token错误、token过期]

{
  "error": "unauthorized",
  "timestamp": 1542602666575,
  "duration": 0,
  "exception": "org.apache.shiro.authz.UnauthorizedException",
  "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]"
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试