用户在线状态管理 RESTful API

更新时间：2022 年 5 月 19 日

本文主要介绍用户在线状态相关 RESTful API 接口。

该功能需联系商务开通。

认证方式

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization：Bearer ${YourAppToken}

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 建议使用 App Token 的鉴权方式，详见使用 Token 鉴权。

用户在线状态管理具体接口

环信即时通讯 IM 提供多个接口实现用户在线状态的设置、订阅、获取、取消订阅以及查询订阅列表等管理功能。

名称 请求 描述
设置用户在线状态信息 /{org_name}/{app_name}/users/{uid}/presence/{resource}/{status} 根据用户的唯一 ID 设置在线状态信息。
批量订阅在线状态 /{org_name}/{app_name}/users/{uid}/presence/{expiry} 订阅多个用户的在线状态信息。
批量获取在线状态信息 /{org_name}/{app_name}/users/{uid}/presence 获取多个用户的在线状态信息。
取消订阅 /{org_name}/{app_name}/users/{uid}/presence 取消订阅用户的在线状态。
查询订阅列表 /{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100 查询当前用户已订阅在线状态的用户列表。

设置用户在线状态信息

方法：POST

接入点：/{org_name}/{app_name}/users/{uid}/presence/{resource}/{status}

路径参数

参数 类型 是否必需 描述
org_name String 必需 即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在控制台注册项目时填入的应用名称。
uid String 必需 用户在即时通讯服务器端的唯一 ID。
resource String 必需 设备来源。
status String 必需 端状态码。该参数的取值如下：
- 0：离线；
- 1：在线；
- 其他值：自定义在线状态。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型：application/json。
Authorization String 必需 Bearer ${token} Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。

请求体参数

参数 类型 是否必需 说明
ext String 必需 在线状态扩展信息。建议不超过 64 字节。

响应参数

参数 类型 说明
result String 操作结果。设置成功返回’ok’，否则返回相应的错误原因，详见响应码列表。

请求示例

curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/c1/presence/android/0' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"ext":"123"}'

响应示例

{"result":"ok"}%

响应码

状态码 描述
200 请求成功。
400 请求失败，错误原因如下：
- set presence failed：在线状态设置失败；
- ext is too big：在线状态扩展信息长度超过限制；
- resource not exist：设备来源不存在。
401 鉴权失败（无 Token，Token 错误或者过期），请重新获取 Token 再试。
429，503 或者其他 5xx 该接口可能限流了，请稍后重试。
500 服务器内部错误，请联系我们的技术支持团队。

批量订阅在线状态

一次可订阅多个用户的在线状态。

方法：POST

接入点：/{org_name}/{app_name}/users/{uid}/presence/{expiry}

路径参数

参数 类型 是否必需 描述
org_name String 必需 即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在控制台注册项目时填入的应用名称。
uid String 必需 用户在即时通讯服务器上的唯一 ID。
expiry String 必需 订阅时间。

请求头参数

参数 类型 是否必需 描述
Content-Type String 必需 内容类型：application/json。
Authorization String 必需 Bearer ${token} Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。

请求体参数

参数 类型 是否必需 说明
usernames JSON ARRAY 必需 订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。

响应参数

参数 类型 说明
result JSON Array 订阅对象的在线状态信息，以数组形式返回。若订阅失败，返回相应的错误原因，详见响应码列表。
uid String 用户在即时通讯服务器的唯一 ID。
last_time Number 用户最近在线时间。
expiry Number 订阅的过期时间戳。
ext String 用户在线状态扩展信息，建议不超过 64 字节。
status JSON Array 用户多端的状态。该参数的取值如下：
- 0：离线；
- 1：在线；
- 其他值：用户可设置其他值自定义在线状态。

请求示例

curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence/1000' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"usernames":["c2","c3"]}'

响应示例

{"result":[{"uid":"","last_time":"1644466063","expiry":"1645500371","ext":"123","status":{"android":"1","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}},{"uid":"c3","last_time":"1645183991","expiry":"1645500371","ext":"","status":{"android":"0","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}}]}%

响应码

状态码 描述
200 请求成功。
400 请求失败，错误原因如下：you can't sub yourself：无法订阅自己的在线状态；“too many sub prensence`：订阅用户数量超过上限。
401 鉴权失败（无 Token，Token 错误或者过期），请重新获取 Token 再试。
429，503 或者其他 5xx 该接口可能限流了，请稍后重试。
500 服务器内部错误，请联系我们的技术支持团队。

批量获取在线状态信息

方法：POST

接入点：/{org_name}/{app_name}/users/{uid}/presence

路径参数

参数 类型 是否必需 描述
org_name String 必需 即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在控制台注册项目时填入的应用名称。
uid String 必需 用户在即时通讯服务器的唯一 ID。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型：application/json。
Authorization String 必需 Bearer ${token} Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。

请求体参数

参数 类型 是否必需 说明
usernames Array 必需 订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。

响应参数

参数 类型 说明
result JSON Array 订阅对象的在线状态信息，以数组形式返回。若订阅失败，返回相应的错误原因，详见响应码列表。
uid String 用户在即时通讯服务器的唯一 ID。
last_time Number 用户最近在线时间。
ext String 用户在线状态的扩展信息，建议不超过 64 字节。
status JSON Array 用户多端的状态。

请求示例

curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"usernames":["c2","c3"]}'

响应示例

{
"result":[
  {"uid":"c2",
  "last_time":"1644466063",
  "ext":"",
  "status":{"android":"0"}
     },
   {"uid":"c3",
   "last_time":"1644475330",
   "ext":"",
   "status":{
       "android":"0",
       "android":"0"}
    }]
 }

响应码

状态码 描述
200 请求成功。
400 请求失败，错误原因：“too many get presences”（获取在线状态的用户数量超过上限）。
401 鉴权失败（无 Token，Token 错误或者过期），请重新获取 Token 再试。
429，503 或者其他 5xx 该接口可能限流了，请稍后重试。
500 服务器内部错误，请联系我们的技术支持团队。

取消订阅

方法：DELETE

接入点：/{org_name}/{app_name}/users/{uid}/presence

路径参数

参数 类型 是否必需 描述
org_name String 必需 即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在控制台注册项目时填入的应用名称。
uid String 必需 用户在即时通讯服务器唯一 ID。

请求头参数

参数 类型 是否必需 描述
Content-Type String 必需 内容类型：application/json。
Authorization String 必需 Bearer ${token} Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。

请求体参数

参数 类型 是否必需 描述
users Array 必需 订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。

响应参数

参数 类型 说明
result String 取消成功返回“ok”；取消失败返回相应的错误原因，详见响应码列表。

请求示例

curl -X DELETE 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '["c1"]'

响应示例

{"result":"ok"}%

响应码

状态码 描述
200 请求成功。
400 请求失败，错误原因：“too many unsub presences”（取消订阅的用户数量超过上限）。
401 鉴权失败（无 Token，Token 错误或者过期），请重新获取 Token 再试。
429，503 或者其他 5xx 该接口可能限流了，请稍后重试。
500 服务器内部错误，请联系我们的技术支持团队。

查询订阅列表

方法：GET

接入点：/{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100

路径参数

参数 类型 是否必需 描述
org_name String 必需 即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在控制台注册项目时填入的应用名称。
uid String 必需 用户在即时通讯服务器的唯一 ID。
pageNum int 必需 要查询的页码。该参数的值须大于等于 1。
pageSize int 必需 每页显示的订阅用户数量。 该参数的值不得超 500。

请求头参数

参数 类型 是否必需 描述
Content-Type String 必需 内容类型：application/json。
Authorization String 必需 Bearer ${token} Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。

响应参数

参数 类型 说明
result Object 订阅对象在线状态信息，以数组形式返回。若查询失败，返回相应的错误原因，详见响应码列表。
totalnum String 当前订阅的用户总数。
sublist Object 订阅对象的信息，以数组形式返回。
uid String 用户在即时通讯服务器的唯一 ID。
expiry String 订阅的过期时间戳。

请求示例

curl -X GET 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json'

响应示例

{"result":{"totalnum":"2","sublist":[{"uid":"lxml2","expiry":"1645822322"},{"uid":"lxml1","expiry":"1645822322"}]}}%

响应码

状态码 描述
200 请求成功。
400 请求失败，错误原因：“too many queries”（查询次数超过限制）。
401 鉴权失败（无 Token，Token 错误或者过期），请重新获取 Token 再试。
429，503 或者其他 5xx 该接口可能限流了，请稍后重试。
500 服务器内部错误，请联系我们的技术支持团队。