目录

用户体系集成

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

新版文档见:用户体系集成


概述

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

Appkey 数据结构

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

Appkey xxxx 分隔符 xxxx 描述
环信应用的唯一标识org_name #app_name app_name 只能是字母、数字、横线组合。长度不能超过 32 字符。

环信 ID 数据结构

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

名称 字段名 数据类型 描述
环信 ID username String 在 AppKey 的范围内唯一用户名,用户 ID 的长度在 64 字节以内。
用户密码 password String 用户登录环信使用的密码。

环信 ID 使用规则

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

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

另:本文档中可能会交错使用“环信 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请求域名:

数据中心REST API请求地址WebSocket访问域名
国内1区a1.easemob.com 或 a1.easecdn.comim-api-v2.easemob.com 或 im-api-v2.easecdn.com
国内2区a31.easemob.com 或 a31.easecdn.comim-api-v2-31.easemob.com 或 im-api-v2-31.easecdn.com
国内VIP区请咨询商务经理请咨询商务经理
客服专用请咨询商务经理请咨询商务经理
新加坡1区a1-sgp.easemob.com 或 a1-sgp.easecdn.comim-api-sgp-v2.easemob.com 或 im-api-sgp-v2.easecdn.com
美东1区a41.easemob.com 或 a41.easecdn.commsync-api-41.easemob.com 或 msync-api-41.easecdn.com
法兰克福1区a51.easemob.com 或 a51.easecdn.commsync-api-51.easemob.com 或 msync-api-51.easecdn.com

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

注意:

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

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

3.支持 HTTP 和 HTTPS。

获取管理员权限token

环信提供的 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详情页找到
client_secretApp的client_secret,可在app详情页找到
ttl String 必需 token 有效期,单位为秒(s)。此外,也可通过环信即时通讯云控制台设置,参见 用户认证详情页面。该参数值以最新设置为准。

Response Body

参数说明
access_token 有效的token字符串
expires_in token 有效期,单位为秒(s)。
application 当前 App 的 UUID 值

请求示例

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 用户的注册、获取、修改、删除等管理功能。

名称请求描述
注册单个用户/{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 中创建一个新的用户,分两种模式:开放注册授权注册

注意:

注册单个用户(开放)

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

HTTP Request

/{org_name}/{app_name}/users

Request Headers

参数说明
Content-Typeapplication/json

Request Body

参数说明
username环信 ID ;也就是 IM 用户名的唯一登录账号,长度不可超过64个字符长度
password登录密码,长度不可超过64个字符长度
nicknameiOS推送昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,长度不可超过100个字符,如果需要环信存储用户昵称,头像等个人信息的,请参考用户属性

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nicknameiOS推送昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,长度不可超过100个字符
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": "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 用户的唯一登录账号,长度不可超过64个字符长度
password登录密码,长度不可超过64个字符长度
nicknameiOS推送昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,长度不可超过100个字符,如果需要环信存储用户昵称,头像等个人信息的,请参考用户属性

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,环信是不保存用户昵称,头像等个人信息的,需要自己服务器保存并与给自己用户注册的IM用户名绑定
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"  
   }  
 ]' '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权限才能进行操作。每次调用接口时,注册用户数量有最大限制,详见接口限流说明

HTTP Request

/{org_name}/{app_name}/users

Request Headers

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

Request Body

参数说明
username环信 ID ;也就是 IM 用户的唯一登录账号,长度不可超过64个字符
password登录密码,长度不可超过64个字符
nicknameiOS推送昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,长度不可超过100个字符,如果需要环信存储用户昵称,头像等个人信息的,请参考用户属性

Response Body

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

参数说明
uuid用户的UUID,标识字段
type“user”用户类型
username用户名,也就是环信 ID
nickname昵称(可选),在 iOS Apns 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,环信是不保存用户昵称,头像等个人信息的,需要自己服务器保存并与给自己用户注册的IM用户名绑定
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例1

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

请求示例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 中存在已经注册过的 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 在线测试


获取用户token

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

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

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

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

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

HTTP Request

/{org_name}/{app_name}/token

Request Headers

参数说明
Content-Typeapplication/json

Request Body

参数说明
grant_typepassword
username用户名
password密码
ttltoken 有效期,单位为秒(s)。此外,也可通过环信即时通讯云控制台设置,参见 用户认证详情页面。该参数值以最新设置为准。

Response Body

参数说明
access_token 有效的用户token字符串
expires_in token 有效时间,以秒为单位,在有效期内不需要重复获取
user UUID:用户的UUID、type:用户类型、created:创建时间、modified:修改时间、username:用户名、activated:是否激活

请求示例

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 用户的详细信息接口。

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 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,环信是不保存用户昵称,头像等个人信息的,需要自己服务器保存并与给自己用户注册的IM用户名绑定
notification_display_style消息提醒方式,“0”仅通知,“1“通知以及消息详情,没有设置返不会返回
notification_no_disturbing免打扰的设置。”false“代表免打扰关闭,“true”免打扰开启,没有设置返不会返回
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'

可能返回的结果示例

返回值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 推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,环信是不保存用户昵称,头像等个人信息的,需要自己服务器保存并与给自己用户注册的IM用户名绑定
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录
notification_display_style消息提醒方式,“true”仅通知,“false“通知以及消息详情,没有设置则不会返回
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'

可能返回的结果示例

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

HTTP Request

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

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

Request Headers

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

请求示例

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个用户,具体删除哪些并没有指定,可以在返回值中查看到哪些用户被删除掉了。

HTTP Request

/{org_name}/{app_name}/users

Request Headers

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

请求示例

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 用户的登录密码,不需要提供原密码。

HTTP Request

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

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

Request Headers

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

Request Body

参数说明
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'

可能返回的结果示例

返回值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 在线测试


设置推送昵称

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

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昵称(可选),在离线推送时会使用的昵称(仅在推送通知栏内显示的昵称),并不是用户个人信息的昵称,环信是不保存用户昵称,头像等个人信息的,需要自己服务器保存并与给自己用户注册的IM用户名绑定
activated用户是否已激活,“true”已激活,“false“封禁,封禁需要通过解禁接口进行解禁,才能正常登录

请求示例

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 在线测试


设置推送消息展示方式

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

HTTP Request

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

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

Request Headers

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

Request Body

参数说明
notification_display_style“0”仅通知,“1“通知以及消息详情

Response Body

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

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

请求示例

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是否免打扰,false 代表免打扰关闭,true 免打扰开启
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 用户,单用户ID可以添加的好友数量,请参考不同版本数量

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 -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 用户。

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 -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 用户的好友列表。

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 -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 用户的黑名单。

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

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 -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 用户的黑名单中移除用户。将用户从黑名单移除后,恢复到好友,或者未添加好友的用户关系。可以正常的进行消息收发。

HTTP Request

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

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

Request Headers

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

Response Body

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

请求示例

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查看一个用户的在线状态
批量获取用户在线状态/{org_name}/{app_name}/users/batch/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 -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个用户。

HTTP Request

/{org_name}/{app_name}/users/batch/status

Request Headers

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

Request Body

参数说明
usernames“user1”, “user2”,需要查询状态的用户名以数组方式提交,最多不能超过100个

Response Body

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

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

请求示例

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 用户的离线消息数量。

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 -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 用户的离线消息状态,查看用户的离线消息离线消息的状态

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

名称请求描述
用户账号禁用/{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 -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 用户账号的禁用操作,由禁用到解禁操作后,需要用户重新登录。

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 -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 用户状态改为离线,用户需要重新登录才能正常使用。

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 -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 在线测试


上一页:版本更新

下一页:发送消息