====== 用户体系集成 ======

----

===== 数据结构 =====

环信作为一个聊天通道，只需要提供环信 ID 和密码就够了。

^名称	^字段名	^数据类型	^描述^
|环信 ID	|username	|String	|环信 ID 是环信用户的唯一标识，在 AppKey 的范围内唯一|
|用户密码	|password	|String	|用户登录环信使用的密码|

===== 名词解释 =====

当您申请了 AppKey 后，会得到一个 **xxxx#xxxx** 格式的字符串，这个就是您的 AppKey，下文中用到的：

  * **org_name 对应#前面部分**  
  * **app_name 对应#后面部分** 

===== 环信 ID 规则 =====

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

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

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

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

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

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

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

===== 获取 APP 管理员 Token =====

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

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

==== 使用 APP 的 client_id 和 client_secret 获取授权管理员 token ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

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

  * Path: /{org_name}/{app_name}/token
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”}
  * Request Body: {“grant_type”: “client_credentials”,”client_id”: “{APP的client_id}”,”client_secret”: “{APP的client_secret}”}
  * Response Body: 

^Key	^Value^
|access_token	|token 值|
|expires_in	|token 有效时间，以秒为单位，在有效期内不需要重复获取|
|application	|当前 APP 的 UUID 值|

  * 可能的错误码：400（client_id 或 client_secret 错误）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端REST API常见错误码]]

curl 示例：

<code php> 
    curl -X POST "https://a1.easemob.com/easemob-demo/chatdemoui/token" -d '{"grant_type":"client_credentials","client_id":"YXA6wDs-MARqEeSO0VcBzaqg11","client_secret":"YXA6JOMWlLap_YbI_ucz77j-4-mI0dd"}'
</code>

Response 示例：

<code json>
{
  "access_token":"YWMtWY779DgJEeS2h9OR7fw4QgAAAUmO4Qukwd9cfJSpkWHiOa7MCSk0MrkVIco",
  "expires_in":5184000,
  "application":"c03b3e30-046a-11e4-8ed1-5701cdaaa0e4"
}
</code>

===== IM 用户管理 =====

==== 注册 IM 用户[单个] ====


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

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

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

=== 开放注册 ===

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”}
  * Request Body: {“username”:”${用户名}”,”password”:”${密码}”, “nickname”:”${昵称值}”}

注：创建用户时，username 和 password 是必须的，nickname 是可选的，这个 nickname 用于 iOS 推送。如果要在创建用户时设置 nickname，请求 body 是：{“username”:”jliu”,”password”:”123456”, “nickname”:”建国”} 这种形式，下面的示例不包含 nickname。批量注册时同此理。

  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户已存在、用户名或密码为空、用户名不合法[见用户名规则]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -i "https://a1.easemob.com/easemob-demo/chatdemoui/users" -d '{"username":"jliu","password":"123456"}'
</code>

Response 示例：

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

=== 授权注册 ===

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: {“username”:”${用户名}”,”password”:”${密码}”}
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户已存在、用户名或密码为空、用户名不合法[见用户名规则]）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -H "Authorization: Bearer YWMt39RfMMOqEeKYE_GW7tu81AAAAT71lGijyjG4VUIC2AwZGzUjVbPp_4qRD5k" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users" -d '{"username":"jliu","password":"123456"}'
</code>

Response 示例：

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

==== 注册 IM 用户[批量] ====

每次调用接口时，注册用户数量有最大限制，详见[[im:450errorcode:45restastrict|接口限流说明]]。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: [{“username”:”${用户名1}”,”password”:”${密码}”},…,{“username”:”${用户名2}”,”password”:”${密码}”}]
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户已存在、用户名或密码为空、用户名不合法[见用户名规则]）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users" -d '[{"username":"u1", "password":"p1"}, {"username":"u2", "password":"p2"}]'
</code>

Response 示例：

<code json>
{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users",
  "entities" : [ {
    "uuid" : "de73238a-31ca-11e4-bdc9-9fdda213fcaa",
    "type" : "user",
    "created" : 1409570811320,
    "modified" : 1409570811320,
    "username" : "u1",
    "activated" : true
  }, {
    "uuid" : "de86365a-31ca-11e4-aecf-9509b836c0d6",
    "type" : "user",
    "created" : 1409570811445,
    "modified" : 1409570811445,
    "username" : "u2",
    "activated" : true
  } ],
  "timestamp" : 1409570811312,
  "duration" : 802,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>
==== 获取 IM 用户[单个] ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EK5eAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFgtox3M" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/ywuxvxuir6"
</code>

Response 示例：

<code json>
{
  "action" : "get",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/ywuxvxuir6",
  "entities" : [ {
    "uuid" : "628a88ba-dfce-11e3-8cac-51d3cb69b303",
    "type" : "user",
    "created" : 1400556326075,
    "modified" : 1400556326075,
    "username" : "ywuxvxuir6",
    "activated" : true
  } ],
  "timestamp" : 1409574716897,
  "duration" : 57,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 获取 IM 用户[批量] ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

=== 不分页 ===

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: GET
  * URL Params: limit=20
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users?limit=20"
</code>

Response 示例：

<code json>
  {
    "action" : "get",
    "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "params" : {
    "limit" : [ "20" ]
    },
    "path" : "/users",
    "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users?ql=select+*+from+null&limit=20",
    "entities" : [ {
    "uuid" : "fff15c10-df37-11e3-843f-e5b88d483c56",
    "type" : "user",
    "created" : 1400491736144,
    "modified" : 1409055655016,
    "username" : "wjglpgecxu",
    "activated" : true,
    "nickname" : "wjglpgecxu",
    "notifier_name" : "chatdemoui_dev"
  }, {
    "uuid" : "4cca8760-df3c-11e3-8712-9f7483b2df95",
    "type" : "user",
    "created" : 1400493583061,
    "modified" : 1400493583061,
    "username" : "pfs5afofrf",
    "activated" : true
  }, {
    "uuid" : "5918fb7a-df3f-11e3-94d1-1f977e72d55c",
    "type" : "user",
    "created" : 1400494892199,
    "modified" : 1407465728550,
    "username" : "igm8dl8m2e",
    "activated" : true,
    "nickname" : "sadsadsa",
    "notification_display_style" : 0,
    "notification_no_disturbing" : false
  }, {
    "uuid" : "ee6e5a3a-df3f-11e3-bbe9-d3a806493d4a",
    "type" : "user",
    "created" : 1400495142739,
    "modified" : 1400495142739,
    "username" : "lgqieuevag",
    "activated" : true
  }, {
    "uuid" : "6d3ba2ea-df41-11e3-b304-eb2e9192a84a",
    "type" : "user",
    "created" : 1400495784974,
    "modified" : 1400495784974,
    "username" : "quqx6qjmb2",
    "activated" : true
  }, {
    "uuid" : "51b663ba-df42-11e3-8470-cd9881131147",
    "type" : "user",
    "created" : 1400496168299,
    "modified" : 1400496168299,
    "username" : "y0fchl0ps9",
    "activated" : true
  }, {
    "uuid" : "b8b1c32a-df42-11e3-b375-53147ac0d738",
    "type" : "user",
    "created" : 1400496341074,
    "modified" : 1400496341074,
    "username" : "v3y0kf9arx",
    "activated" : true
  }, {
    "uuid" : "8cf86e4a-df61-11e3-8a70-25cc7e73257e",
    "type" : "user",
    "created" : 1400509582116,
    "modified" : 1400509582116,
    "username" : "kapzkr9rro",
    "activated" : true
  }, {
    "uuid" : "a11dca4a-df62-11e3-8551-493bea6a0997",
    "type" : "user",
    "created" : 1400510045412,
    "modified" : 1400510045412,
    "username" : "vkpvscnkzn",
    "activated" : true
  }, {
    "uuid" : "860169a4-df64-11e3-aaae-6bc8d50bc307",
    "type" : "user",
    "created" : 1400510858921,
    "modified" : 1400510858921,
    "username" : "6tkecmjtzn",
    "activated" : true
  }, {
    "uuid" : "1ed6bffa-df68-11e3-80f0-33f2237fa6e0",
    "type" : "user",
    "created" : 1400512403823,
    "modified" : 1400512403823,
    "username" : "xc6xrnbzci",
    "activated" : true
  }, {
    "uuid" : "5472a84a-df68-11e3-b0b9-735c1b1db9a1",
    "type" : "user",
    "created" : 1400512493764,
    "modified" : 1400512493764,
    "username" : "vrhfk5lxsz",
    "activated" : true
  }, {
    "uuid" : "79b3db1a-dfbd-11e3-9c5d-3be5e57070a5",
    "type" : "user",
    "created" : 1400549063489,
    "modified" : 1400549063489,
    "username" : "qmlu5szkbm",
    "activated" : true
  }, {
    "uuid" : "3a2416ea-dfc2-11e3-a3e8-238b964488ee",
    "type" : "user",
    "created" : 1400551104334,
    "modified" : 1400551104334,
    "username" : "6pxxbfcnxu",
    "activated" : true
  }, {
    "uuid" : "65f6cf1a-dfc2-11e3-9dad-2929901f1b97",
    "type" : "user",
    "created" : 1400551177857,
    "modified" : 1400551177857,
    "username" : "xffslraxae",
    "activated" : true
  }, {
    "uuid" : "2631911a-dfc9-11e3-803d-23343cadc4ed",
    "type" : "user",
    "created" : 1400554077345,
    "modified" : 1400554077345,
    "username" : "pfxfc9ggkz",
    "activated" : true
  }, {
    "uuid" : "4295acaa-dfca-11e3-9bf1-5fd8df7f7659",
    "type" : "user",
    "created" : 1400554554474,
    "modified" : 1400554554474,
    "username" : "pksaxc6pao",
    "activated" : true
  }, {
    "uuid" : "8c76072a-dfca-11e3-acc7-7dbd7c3dd494",
    "type" : "user",
    "created" : 1400554678418,
    "modified" : 1400554678418,
    "username" : "s1yqttgtya",
    "activated" : true
  }, {
    "uuid" : "93d710ea-dfca-11e3-a6e8-4f903c0b10fb",
    "type" : "user",
    "created" : 1400554690798,
    "modified" : 1400554690798,
    "username" : "qihp1et8t4",
    "activated" : true
  }, {
    "uuid" : "b1fbbdaa-dfca-11e3-a242-8d6201f83c2b",
    "type" : "user",
    "created" : 1400554741370,
    "modified" : 1400554741370,
    "username" : "0vwy72min6",
    "activated" : true
  } ],
    "timestamp" : 1409571908388,
    "duration" : 747,
    "organization" : "easemob-demo",
    "applicationName" : "chatdemoui",
    "cursor" : "LTU2ODc0MzQzOnNmdTlxdF9LRWVPaVFvMWlBZmc4S3c",
    "count" : 20
   }
</code>   
   
=== 分页 ===

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: GET
  * URL Params: limit=20&cursor=LTU2ODc0MzQzOnNmdTlxdF9LRWVPaVFvMWlBZmc4S3c
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFgtox3M" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users?limit=20&cursor=LTU2ODc0MzQzOnNmdTlxdF9LRWVPaVFvMWlBZmc4S3c"
</code>

Response 示例：

<code json>
  {
    "action" : "get",
    "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "params" : {
    "limit" : [ "20" ],
    "cursor" : [ "LTU2ODc0MzQzOnNmdTlxdF9LRWVPaVFvMWlBZmc4S3c" ]
   },
    "path" : "/users",
    "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users?ql=select+*+from+null&limit=20",
    "entities" : [ {
    "uuid" : "db8b63aa-dfca-11e3-b938-0337d3f77124",
    "type" : "user",
    "created" : 1400554811098,
    "modified" : 1400554811098,
    "username" : "an9hmj9js2",
    "activated" : true
   }, {
    "uuid" : "e4fab3fa-dfca-11e3-a4ce-59804f43b0c8",
    "type" : "user",
    "created" : 1400554826927,
    "modified" : 1400554826927,
    "username" : "3qwepp6xkg",
    "activated" : true
   }, {
    "uuid" : "f844e7aa-dfca-11e3-9eb4-3d526f9ecfeb",
    "type" : "user",
    "created" : 1400554859290,
    "modified" : 1400554859290,
    "username" : "ce41dtafer",
    "activated" : true
   }, {
    "uuid" : "fc4f4c5a-dfca-11e3-aaf8-239a98c53960",
    "type" : "user",
    "created" : 1400554866069,
    "modified" : 1400554866069,
    "username" : "2ewcgkhhxf",
    "activated" : true
   }, {
    "uuid" : "0005ebba-dfcb-11e3-9704-f734eb21dbc4",
    "type" : "user",
    "created" : 1400554872299,
    "modified" : 1400554872299,
    "username" : "zh9w1hc49q",
    "activated" : true
   }, {
    "uuid" : "7f8e638a-dfcb-11e3-971e-fdc9e466fac1",
    "type" : "user",
    "created" : 1400555086264,
    "modified" : 1400555086264,
    "username" : "lxrpebngsl",
    "activated" : true
   }, {
    "uuid" : "2d7fa7ba-dfcc-11e3-8b04-5f7a1794920c",
    "type" : "user",
    "created" : 1400555378091,
    "modified" : 1400555378091,
    "username" : "yeimn3szbh",
    "activated" : true
   }, {
    "uuid" : "3cc89e7a-dfcc-11e3-9a11-f1c6519f66af",
    "type" : "user",
    "created" : 1400555403735,
    "modified" : 1400555403735,
    "username" : "7s5e3jtieh",
    "activated" : true
   }, {
    "uuid" : "7cc785ea-dfcc-11e3-b24a-d5b4112501a1",
    "type" : "user",
    "created" : 1400555511102,
    "modified" : 1400555511102,
    "username" : "5cxhactgdj",
    "activated" : true
   }, {
    "uuid" : "ba8b717a-dfcc-11e3-85ca-3db38b18c75d",
    "type" : "user",
    "created" : 1400555614727,
    "modified" : 1400555614727,
    "username" : "qjf8b3r6q8",
    "activated" : true
   }, {
    "uuid" : "d5ad176a-dfcc-11e3-9e67-d933f3e27add",
    "type" : "user",
    "created" : 1400555660246,
    "modified" : 1400555660246,
    "username" : "mh2kbjyop1",
    "activated" : true
   }, {
    "uuid" : "2d4bf81a-dfcd-11e3-9e57-eb0fac2d4582",
    "type" : "user",
    "created" : 1400555807249,
    "modified" : 1400555807249,
    "username" : "q4xpsfjfvf",
    "activated" : true
   }, {
    "uuid" : "65368b5a-dfcd-11e3-8a1a-b9f751cf717c",
    "type" : "user",
    "created" : 1400555901061,
    "modified" : 1400555901061,
    "username" : "r1xnbh79us",
    "activated" : true
   }, {
    "uuid" : "6a9423fa-dfcd-11e3-8841-c1c4a8c96d7d",
    "type" : "user",
    "created" : 1400555910063,
    "modified" : 1400555910063,
    "username" : "sofa8kyoca",
    "activated" : true
   }, {
    "uuid" : "1698653a-dfce-11e3-8524-89dd680b7ce4",
    "type" : "user",
    "created" : 1400556198659,
    "modified" : 1400556198659,
    "username" : "4lo3srucvl",
    "activated" : true
   }, {
    "uuid" : "236b79fa-dfce-11e3-a9a3-250f2047b4bc",
    "type" : "user",
    "created" : 1400556220175,
    "modified" : 1400556220175,
    "username" : "w2k0etnjjj",
    "activated" : true
   }, {
    "uuid" : "54eb716a-dfce-11e3-9781-ab12107b7351",
    "type" : "user",
    "created" : 1400556303222,
    "modified" : 1400556303222,
    "username" : "ir4ad2dqri",
    "activated" : true
   }, {
    "uuid" : "5bb51d2a-dfce-11e3-be10-4ff224c17422",
    "type" : "user",
    "created" : 1400556314610,
    "modified" : 1400556314610,
    "username" : "0fktzcr36b",
    "activated" : true
   }, {
    "uuid" : "60cf6b3a-dfce-11e3-b8bf-ed78a8f851f8",
    "type" : "user",
    "created" : 1400556323171,
    "modified" : 1400556323171,
    "username" : "ytbdzt3w9e",
    "activated" : true
   }, {
    "uuid" : "628a88ba-dfce-11e3-8cac-51d3cb69b303",
    "type" : "user",
    "created" : 1400556326075,
    "modified" : 1400556326075,
    "username" : "ywuxvxuir6",
    "activated" : true
   } ],
    "timestamp" : 1409574113435,
    "duration" : 2812,
    "organization" : "easemob-demo",
    "applicationName" : "chatdemoui",
    "cursor" : "LTU2ODc0MzQzOllvcUl1dF9PRWVPTXJGSFR5Mm16QXc",
    "count" : 20
  }
</code>
  
==== 删除 IM 用户[单个] ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

**注意：**删除一个用户会删除以该用户为群主的所有群组和聊天室。

  * Path: /{org_name}/{app_name}/users/{username}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EK5eAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFgtox3M" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/ywuxvxuir6"
</code>

Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users",
  "entities" : [ {
    "uuid" : "628a88ba-dfce-11e3-8cac-51d3cb69b303",
    "type" : "user",
    "created" : 1400556326075,
    "modified" : 1400556326075,
    "username" : "ywuxvxuir6",
    "activated" : true
  } ],
  "timestamp" : 1409576121910,
  "duration" : 3330,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 删除 IM 用户[批量] ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users
  * HTTP Method: DELETE
  * URL Params: limit=N，N指定删除数据的最大条数
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EK5eAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFgtox3M" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users?limit=5"
</code>

Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : {
    "limit" : [ "5" ]
  },
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users",
  "entities" : [ {
    "uuid" : "fff15c10-df37-11e3-843f-e5b88d483c56",
    "type" : "user",
    "created" : 1400491736144,
    "modified" : 1409055655016,
    "username" : "wjglpgecxu",
    "activated" : true,
    "nickname" : "wjglpgecxu",
    "notifier_name" : "chatdemoui_dev"
  }, {
    "uuid" : "4cca8760-df3c-11e3-8712-9f7483b2df95",
    "type" : "user",
    "created" : 1400493583061,
    "modified" : 1400493583061,
    "username" : "pfs5afofrf",
    "activated" : true
  }, {
    "uuid" : "5918fb7a-df3f-11e3-94d1-1f977e72d55c",
    "type" : "user",
    "created" : 1400494892199,
    "modified" : 1407465728550,
    "username" : "igm8dl8m2e",
    "activated" : true,
    "nickname" : "sadsadsa",
    "notification_display_style" : 0,
    "notification_no_disturbing" : false
  }, {
    "uuid" : "ee6e5a3a-df3f-11e3-bbe9-d3a806493d4a",
    "type" : "user",
    "created" : 1400495142739,
    "modified" : 1400495142739,
    "username" : "lgqieuevag",
    "activated" : true
  }, {
    "uuid" : "6d3ba2ea-df41-11e3-b304-eb2e9192a84a",
    "type" : "user",
    "created" : 1400495784974,
    "modified" : 1400495784974,
    "username" : "quqx6qjmb2",
    "activated" : true
  } ],
  "timestamp" : 1409576576785,
  "duration" : 9426,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui",
  "cursor" : "LTU2ODc0MzQzOmJUdWk2dDlCRWVPekJPc3VrWktvU2c"
}
</code>

==== 重置 IM 用户密码 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/password
  * HTTP Method: PUT
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: {“newpassword” : “${新密码指定的字符串}”}
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（错误请求）、404（用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFgtox3M" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/ywuxvxuir6/password" -d '{"newpassword" : "123456"}'
</code>

Response 示例：

<code json>
{
  "action" : "set user password",
  "timestamp" : 1409575962124,
  "duration" : 326
}
</code>

==== 修改用户推送显示昵称 ====

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}
  * HTTP Method: PUT
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: {“nickname” : “${昵称值}”}
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（用户不存在、错误请求）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端REST API常见错误码]]

curl 示例：

<code php>
curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/jianguo" -d '{"nickname" : "张建国"}'
</code>

Response 示例：

<code json>
{
  "action" : "put",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "path" : "/users",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users",
  "entities" : [ {
    "uuid" : "c3b56d5a-7135-11e4-92d2-edab82ae2302",
    "type" : "user",
    "created" : 1416543645861,
    "modified" : 1416550240537,
    "username" : "jianguo",
    "activated" : true,
    "device_token" : "61491f49f3e69cd1d62c5b390e42f4b1cd15bf1a876a487268cfaef9960188ee",
    "nickname" : "张建国"
  } ],
  "timestamp" : 1416550240285,
  "duration" : 278,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

===== 好友与黑名单 =====

==== 给 IM 用户添加好友 ====

给一个用户添加好友，好友必须是和自己在一个 APP 下的 IM 用户，每个用户的好友数量上限为1000。{owner_username} 是要添加好友的用户名，{friend_username} 是被添加的用户名。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此IM用户或被添加的好友不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEU2" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/jliu/contacts/users/yantao"
</code>

Response 示例：

<code json>
{
  "action": "post",
  "application":"4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "path":"/users/aa6160da-eb01-11e3-ab09-15edd986e7b7/contacts",
  "uri":"https://a1.easemob.com/easemob-demo/chatdemoui/users/jliu/contacts/yantao",
  "entities": [
    {
      "uuid":"0086742a-dc9b-11e3-a782-1b5d581c57a9",
      "type":"user",
      "created":1400204403810,
      "modified":1400204403810,
      "username":"yantao",
      "activated":true
    }
  ],
  "timestamp": 1489128716085,
  "duration": 104,
  "organization":"easemob-demo",
  "applicationName":"chatdemoui"
}
</code>
==== 解除 IM 用户的好友关系 ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此 IM 用户或被解除的好友不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE -i -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEU2" "https://a1.easemob.com/easemob-demo/chatdemoui/users/stliu/contacts/users/yantao"
</code>

Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "params" : { },
  "path" : "/users/stliu/contacts",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/stliu/contacts/users/yantao",
  "entities" : [ {
    "uuid" : "aa6160da-eb01-11e3-ab09-15edd986e7b7",
    "type" : "user",
    "created" : 1401787813725,
    "modified" : 1409739134225,
    "username" : "88888",
    "activated" : true,
    "device_token" : "67aab3a88a0b146b7883e7b0275ffe94f509a4e69e8b1db503b2fa4f9c556dd3",
    "nickname" : "88888",
    "notification_display_style" : 0,
    "notification_no_disturbing" : false,
    "notification_no_disturbing_end" : 24,
    "notification_no_disturbing_start" : 0,
    "notifier_name" : "chatdemoui_dev"
  } ],
  "timestamp" : 1409739808288,
  "duration" : 1575,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 获取 IM 用户的好友列表 ====

查看某个 IM 用户的好友信息。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/contacts/users
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此 IM 用户或要查看的好友不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEU2" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/contacts/users"
</code>

Response 示例：

<code json>
{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/contacts/users",
  "entities": [],
  "data": [
    "ss01",
    "ss05",
    "ss09"
  ],
  "timestamp" : 1409737366071,
  "duration" : 45,
  "count": 3
}
</code>
==== 获取 IM 用户的黑名单 ====

获取一个IM用户的黑名单。黑名单中的用户无法给该 IM 用户发送消息。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/blocks/users
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: “data” : [ “stliu2” ] — 黑名单中的用户的用户名：stliu2
  * 可能的错误码：404（此 IM 用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtwIRGSE9gEeSbpNnVBsIhiwAAAUon2XDyEBoBUk6Vg2xm8DZdVjxbhwm7XWY" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/blocks/users"
</code>

Response 示例：
<code json>
{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/blocks/users",
  "entities" : [ ],
  "data" : [ "stliu2" ],
  "timestamp" : 1412824409803,
  "duration" : 36
}
</code>

==== 往 IM 用户的黑名单中加人 ====

往一个 IM 用户的黑名单中加人，一次可以添加一个或多个，黑名单中的用户无法给该 IM 用户发送消息，每个用户的黑名单人数上限为500。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/blocks/users
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: {“usernames”:[“5cxhactgdj”, “mh2kbjyop1”]} —- 需要加入到黑名单中的用户名以数组方式提交，usernames 为关键字不变
  * Response Body: “data” : [ “5cxhactgdj”, “mh2kbjyop1” ] — 已经加到黑名单中的用户名：5cxhactgdj、mh2kbjyop1
  * 可能的错误码：404（此 IM 用户不存在）、400（被添加的IM用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -H 'Authorization: Bearer YWMtwIRGSE9gEeSbpNnVBsIhiwAAAUon2XDyEBoBUk6Vg2xm8DZdVjxbhwm7XWY' -i  'https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/blocks/users' -d '{"usernames":["5cxhactgdj", "mh2kbjyop1"]}'
</code>

Response 示例：

<code json>
{
  "action" : "post",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui",
  "entities" : [ ],
  "data" : [ "5cxhactgdj", "mh2kbjyop1" ],
  "timestamp" : 1412825162092,
  "duration" : 15,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

==== 从 IM 用户的黑名单中减人 ====

从一个 IM 用户的黑名单中减人。将用户从黑名单移除后，恢复好友关系，可以互相收发消息。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}
  * HTTP Method: DELETE
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: entities 中包含了刚刚从黑名单中移除的 IM 用户的详细信息
  * 可能的错误码：404（此 IM 用户或被减的用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X DELETE -H 'Authorization: Bearer YWMtwIRGSE9gEeSbpNnVBsIhiwAAAUon2XDyEBoBUk6Vg2xm8DZdVjxbhwm7XWY' -i  'https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/blocks/users/5cxhactgdj'
</code>

Response 示例：

<code json>
{
  "action" : "delete",
  "application" : "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
  "path" : "/users/72bb4f9a-fce7-11e3-98f4-adc39e9f4363/blocks",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/blocks",
  "entities" : [ {
    "uuid" : "7cc785ea-dfcc-11e3-b24a-d5b4112501a1",
    "type" : "user",
    "created" : 1400555511102,
    "modified" : 1400555511102,
    "username" : "5cxhactgdj",
    "activated" : true
  } ],
  "timestamp" : 1412825354550,
  "duration" : 164,
  "organization" : "easemob-demo",
  "applicationName" : "chatdemoui"
}
</code>

===== 在线与离线 =====

==== 查看用户在线状态 ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/status
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：
<code php>
curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/users/zw123/status"
</code>

Response 示例：

<code json>
{
    "action": "get",
    "application": "4d7e4ba0-dc4a-11e3-90d5-e1ffbaacdaf5",
    "params": {},
    "uri": "https://a1.easemob.com/easemob-demo/chatdemoui",
    "entities": [],
    "data": {
        "stliu": "online"  //注意：这里返回的是用户名和在线状态的键值对，值为 online 或者 offline
    },
    "timestamp": 1404932199220,
    "duration": 743,
    "organization": "easemob-demo",
    "applicationName": "chatdemoui"
}
</code>

==== 查询离线消息数 ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{owner_username}/offline_msg_count
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: “data” : {“v3y0kf9arx” : 0 } —- 用户名：v3y0kf9arx，离线消息数：0条
  * 可能的错误码：404（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -H "Authorization: Bearer YWMtwIRGSE9gEeSbpNnVBsIhiwAAAUon2XDyEBoBUk6Vg2xm8DZdVjxbhwm7XWY" -i  "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/offline_msg_count"
</code>

Response 示例：

<code json>
{
  "action" : "get",
  "uri" : "https://a1.easemob.com/easemob-demo/chatdemoui/users/v3y0kf9arx/offline_msg_count",
  "entities" : [ ],
  "data" : {
    "v3y0kf9arx" : 0
  },
  "timestamp" : 1412823831894,
  "duration" : 57
}
</code>

==== 查询某条离线消息状态 ====

通过离线消息的 ID 查看用户的该条离线消息状态。消息ID可以通过[[start:100serverintegration:30chatlog#获取聊天记录|获取聊天记录]]查询。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：404（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/users/zw123/offline_msg_status/1121212"
</code>

Response 示例：

<code json>
{
    "action": "get",
    "uri": "http://a2.easemob.com/easemob-demo/chatdemoui/users/jianxin/offline_msg_status/12",
    "entities": [],
    "data": {
        "12": "delivered"      // 格式："{消息id}":"{状态}"，状态的值有两个: deliverd表示此用户的该条离线消息已经收到过了，undelivered表示此用户的该条离线消息还未收到
    },
    "timestamp": 1423573644082,
    "duration": 644
}
</code>

===== 账号禁用与解禁 =====

==== 用户账号禁用 ====

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

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/deactivate
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/users/zw123/deactivate"
</code>

Response 示例：

<code json>
{
    "action": "Deactivate user",
    "entities": [
        {
            "uuid": "3861665a-07e5-11e4-b1d3-b70cde5a834c",
            "type": "user",
            "created": 1404964180277,
            "modified": 1424781662293,
            "username": "zw123",
            "activated": false,
            "nickname": "zw123"
        }
    ],
    "timestamp": 1424846198409,
    "duration": 244
}
</code>

==== 用户账号解禁 ====

解除对某个 IM 用户账号的禁用，解禁后用户恢复正常使用。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/activate
  * HTTP Method: POST
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：400（此用户不存在）、401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X POST -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/users/zw123/activate"
</code>

Response 示例：

<code json>
{
    "action": "activate user",
    "timestamp": 1424845777195,
    "duration": 2
}
</code>

===== 强制用户下线 =====

如果某个 IM 用户已经登录环信服务器，强制其退出登录。

<WRAP round tip>
注意：在调用程序中，如果返回429或503错误，说明接口被限流了，请稍微暂停一下并重试。详见[[start:450errorcode:45restastrict|接口限流说明]]。
</WRAP>

  * Path: /{org_name}/{app_name}/users/{username}/disconnect
  * HTTP Method: GET
  * URL Params: 无
  * Request Headers: {“Content-Type”:”application/json”,”Authorization”:”Bearer ${token}”}
  * Request Body: 无
  * Response Body: 详情参见示例返回值，返回的 JSON 数据中会包含除上述属性之外的一些其他信息，均可以忽略。
  * 可能的错误码：401（未授权[无token、token错误、token过期]）、5xx。详见：[[start:450errorcode:10restapierrorcode|服务器端 REST API 常见错误码]]

curl 示例：

<code php>
curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9Ocqq-GwPsKwj_TruuxZfFSC2eIQ" "https://a1.easemob.com/easemob-demo/chatdemoui/users/zw123/disconnect"
</code>

Response 示例：

<code json>
{
  "action" : "Disconnect user",
  "data" : {
    "result" : true    // true表示强制下线成功，false表示强制用户下线失败
  },
  "timestamp" : 1430825373659,
  "duration" : 16
}
</code>


----
<WRAP group>
<WRAP half column>
上一页：[[start:100serverintegration:10intro|入门]]
</WRAP>

<WRAP half column>
下一页：[[start:100serverintegration:30chatlog|聊天记录]]
</WRAP>
</WRAP>