用户体系集成


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

Appkey 数据结构

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

Appkey xxxx 分隔符 xxxx
环信应用的唯一标识org_name #app_name

环信 ID 数据结构

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

名称 字段名 数据类型 描述
环信 ID username String AppKey 的范围内唯一的 IM 用户名
用户密码 password String 用户登录环信使用的密码

环信 ID 使用规则

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

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

  • 使用英文字母和(或)数字的组合
  • 不能使用中文
  • 不能使用 email 地址
  • 不能使用 UUID
  • 用户ID的长度在255字节以内
  • 中间不能有空格或者井号(#)等特殊字符
  • 允许的用户名正则 “[a-zA-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 很容易被反编译,从而导致别人获取到您的管理员账号和密码,导致数据泄露。


REST API

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

环信提供的 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 详情页面看到。

HTTP Request

/{org_name}/{app_name}/token

Request Headers

参数说明
Content-Typeapplication/json

Request Body

参数说明
grant_typeclient_credentials
client_idApp的client_id,可在app详情页找到
client_secretApp的client_secret,可在app详情页找到

Response Body

参数说明
access_token 有效的token字符串
expires_in token 有效时间,以秒为单位,在有效期内不需要重复获取
application 当前 App 的 UUID 值

请求示例

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "grant_type": "client_credentials", \ 
   "client_id": "YXA6i-Ak8Ol4Eei2l11ZjV-EAg", \ 
   "client_secret": "YXA6VunqiNxoB7IwXHInk1cGiXOOJfc" \ 
 }' '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 错误

{
  "error_description": "client_id does not match",
  "error": "invalid_grant"
}

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

使用 Easemob REST API 在线测试


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

名称请求描述
注册单个用户/{org_name}/{app_name}/users注册一个 IM 用户,有开放注册授权注册两种模式
批量注册用户/{org_name}/{app_name}/users注册多个 IM 用户,仅支持授权注册
获取单个用户/{org_name}/{app_name}/users/{username}获取单个 IM 用户
批量获取用户/{org_name}/{app_name}/users获取应用下的多个 IM 用户
删除单个用户/{org_name}/{app_name}/users/{username}删除单个 IM 用户
批量删除用户/{org_name}/{app_name}/users批量删除多个 IM 用户
修改用户密码/{org_name}/{app_name}/users/{username}/password修改 IM 用户的密码
设置推送消息显示昵称/{org_name}/{app_name}/users/{username}设置 IM 用户推送消息显示的昵称
设置推送消息展示方式/{org_name}/{app_name}/users/{username}设置 IM 用户推送消息展示为仅通知还是详情可见
设置免打扰/{org_name}/{app_name}/users/{username}设置 IM 用户是否开启免打扰模式,以及开启/关闭免打扰的时间

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

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

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

注册单个用户(开放)

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

HTTP Request

/{org_name}/{app_name}/users

Request Headers

参数说明
Content-Typeapplication/json

Request Body

参数说明
username环信 ID ;也就是 IM 用户名的唯一登录账号
password登录密码
nickname昵称(可选),在 iOS Apns 推送时会使用的昵称

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称,在 iOS Apns 推送时会使用的昵称,没有设置则不会返回
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例

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

可能返回的结果示例

返回值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权限才能进行操作,授权注册的接口。

HTTP Request

/{org_name}/{app_name}/users

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
username环信 ID ;也就是 IM 用户的唯一登录账号
password登录密码
nickname昵称(可选),在 iOS Apns 推送时会使用的昵称,没有设置返则不会返回

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称,在 iOS Apns 推送时会使用的昵称,,没有设置返则不会返回
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例

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

可能返回的结果示例

返回值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权限才能进行操作。每次调用接口时,注册用户数量有最大限制,详见接口限流说明

HTTP Request

/{org_name}/{app_name}/users

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
username环信 ID ;也就是 IM 用户的唯一登录账号
password登录密码
nickname昵称(可选),在 iOS Apns 推送时会使用的昵称

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称,在 iOS Apns 推送时会使用的昵称,没有设置返则不会返回
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"}]'

可能返回的结果示例

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

{
  "action": "post",
  "application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d",
  "path": "/users",
  "uri": "https://a1.easemob.com/1122161011178276/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,
  "duration": 0,
  "organization": "1122161011178276",
  "applicationName": "testapp"
}

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

使用 Easemob REST API 在线测试


获取单个用户

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

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录
nickname昵称,在 iOS Apns 推送时会使用的昵称,没有设置返则不会返回
notification_no_disturbing消息提醒方式,“true”仅通知,“false“通知以及消息详情,没有设置返则不会返回
notification_display_style免打扰的设置。“0”代表免打扰关闭,“1”免打扰开启,没有设置返则不会返回
notification_no_disturbing_start免打扰的开始时间。数字代表开始时间,例如“8”代表每日8:00开启免打扰,没有设置返则不会返回
notification_no_disturbing_end免打扰的结束时间。数字代表结束时间,例如“18”代表每日18:00关闭免打扰,没有设置返则不会返回
notifier_name客户端推送证书名称,没有设置返则不会返回

请求示例

curl -X GET --header 'Accept: application/json' --header '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的意义在于数据(真)分页。

HTTP Request

/{org_name}/{app_name}/users

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称,在 iOS Apns 推送时会使用的昵称,没有设置返则不会返回
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录
notification_no_disturbing消息提醒方式,“true”仅通知,“false“通知以及消息详情,没有设置返则不会返回
notification_display_style免打扰的设置。“0”代表免打扰关闭,“1”免打扰开启,没有设置返则不会返回
notification_no_disturbing_start免打扰的开始时间。数字代表开始时间,例如“8”代表每日8:00开启免打扰,没有设置返则不会返回
notification_no_disturbing_end免打扰的结束时间。数字代表结束时间,例如“18”代表每日18:00关闭免打扰,没有设置返则不会返回
notifier_name客户端推送证书名称,没有设置返则不会返回
不分页

请求示例

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

可能返回的结果示例

返回值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 --header 'Accept: application/json' --header '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,系统会同时删除这些群组和聊天室。请在操作时进行确认。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

请求示例

curl -X DELETE --header 'Accept: application/json' --header '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个用户,具体删除哪些并没有指定,可以在返回值中查看到哪些用户被删除掉了。

HTTP Request

/{org_name}/{app_name}/users

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

请求示例

curl -X DELETE --header 'Accept: application/json' --header '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 用户的登录密码,不需要提供原密码。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
newpassword${新密码指定的字符串}

请求示例

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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"
}

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

''待补充''

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

使用 Easemob REST API 在线测试


设置推送消息显示昵称

设置用户的推送昵称,在 iOS APNS 推送时使用。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
nickname将要改成的昵称信息

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称,在 iOS Apns 推送时会使用的昵称
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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 在线测试


设置推送消息展示方式

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

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
notification_no_disturbing“true”仅通知,“false“通知以及消息详情

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录
notification_no_disturbing消息提醒方式,“true”仅通知,“false“通知以及消息详情

请求示例

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 用户免打扰,在免打扰期间,用户将不会收到消息通知。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
notification_no_disturbing是否免打扰,“0”代表免打扰关闭,“1”免打扰开启
notification_no_disturbing_start免打扰起始时间,单位是小时
notification_no_disturbing_end免打扰结束时间,单位是小时

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录
notification_display_style免打扰的设置。“0”代表免打扰关闭,“1”免打扰开启
notification_no_disturbing_start免打扰的开始时间。数字代表开始时间,例如“8”代表每日8:00开启免打扰
notification_no_disturbing_end免打扰的结束时间。数字代表结束时间,例如“18”代表每日18:00关闭免打扰

请求示例

设置免打扰时间

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 用户的好友以及黑名单进行添加和移除。

名称请求描述
添加好友/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}添加为好友
移除好友/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}移除好友列表中的用户
获取好友列表/{org_name}/{app_name}/users/{owner_username}/contacts/users获取好友列表以及信息
获取黑名单/{org_name}/{app_name}/users/{owner_username}/blocks/users获取黑名单以及信息
添加黑名单/{org_name}/{app_name}/users/{owner_username}/blocks/users拉黑用户,添加至黑名单
移除黑名单/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}除黑名单中的用户

添加好友

添加好友,好友必须是和自己在一个 APPkey 下的 IM 用户,每个用户的好友数量上限为1000。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

请求示例

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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 用户。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

请求示例

curl -X DELETE --header 'Accept: application/json' --header '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 用户的好友列表。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

参数说明
username“user1”, “user2”,获取到的好友列表

请求示例

curl -X GET --header 'Accept: application/json' --header '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 用户的黑名单。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

参数说明
username“user1”, “user2”,获取到的黑名单列表

请求示例

curl -X GET --header 'Accept: application/json' --header '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。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
usernames“user1”, “user2”,需要加入到黑名单中的用户名以数组方式提交

Response Body

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

参数说明
username这里会把已添加至内名单的用户名进行展示

请求示例

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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 用户的黑名单中移除用户。将用户从黑名单移除后,恢复到好友,或者未添加好友的用户关系。可以正常的进行消息收发。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Request Body

参数说明
username“user1”, “user2”,需要移除黑名单中的用户名以数组方式提交

Response Body

参数说明
entities从黑名单中移除的 IM 用户的详细信息

请求示例

curl -X DELETE --header 'Accept: application/json' --header '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查看一个用户的在线状态
获取离线消息数/{org_name}/{app_name}/users/{owner_username}/offline_msg_count获取一个 IM 用户的离线消息数
获取离线消息的状态/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}通过离线消息的 ID 查看用户的该条离线消息状态

获取用户在线状态

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

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
username会显示为“user1”对应就是查询的username,“offline”代表离线,“online”在表用户当前在线

请求示例

curl -X GET --header 'Accept: application/json' --header '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 在线测试


获取用户离线消息数

获取 IM 用户的离线消息数量。默认的离线消息数量上限为1200条。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
username会显示为“user1”对应就是查询的username,“数字”当前离线消息的数量

请求示例

curl -X GET --header 'Accept: application/json' --header '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 用户的离线消息状态,查看用户的离线消息离线消息的状态

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
msg_id“对应的ID编号”,表示为对应的消息id, “delivered”表示状态为消息已投递,“undelivered”表示消息未投递

请求示例

curl -X GET --header 'Accept: application/json' --header '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": {
    "testmessage": "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 用户的禁用以及解禁接口操作,对用户禁用用户将立即下线并无法登录进入环信,直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。

名称请求描述
用户账号禁用/{org_name}/{app_name}/users/{username}/deactivate禁用用户的登录账号,必须通过解禁才能恢复
用户账号解禁 /{org_name}/{app_name}/users/{username}/activate解禁后用户恢复正常使用

用户账号禁用

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

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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 用户账号的禁用操作,由禁用到解禁操作后,需要用户重新登录。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

参数说明
action操作,“activate user“表示解禁/激活 IM 用户

请求示例

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header '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 用户状态改为离线,用户需要重新登录才能正常使用。

HTTP Request

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

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

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

Response Body

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

参数说明
result操作结果,“true”表示用户已经被强制下线

请求示例

curl -X GET --header 'Accept: application/json' --header '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 在线测试


上一页:版本更新

下一页:发送消息