服务端 API

查询用户在线状态

使用 查询用户在线状态 从可信后端批量获取用户当前是否在线，以及在线终端的连接信息。接口会聚合所有消息网关上的长连接状态；未在线的用户也会出现在响应中，status 为 0。

HTTP 请求

POST {API_ADDRESS}/user/get_users_online_status

请求示例

curl --request POST "${API_ADDRESS}/user/get_users_online_status" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: 1646445464564" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "userIDs": ["user_001", "user_002"]
}'

安全提示：管理员 Token 只能保存在可信后端服务中，不能下发到客户端或写入前端代码。在线状态通常用于运营后台、风控和服务端调度，不建议由客户端直接查询。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递用户 ID 列表。

请求头

请求头	示例值	是否必填	类型	说明
operationID	1646445464564	必填	string	用于全局链路追踪，建议每个请求独立生成。
token	eyJhbxxxx3Xs	必填	string	管理员 token。

请求体参数

{
  "userIDs": ["user_001", "user_002"]
}

参数名	是否必填	类型	说明
userIDs	必填	array	需要查询在线状态的用户 ID 列表。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": [
    {
      "userID": "user_001",
      "status": 1,
      "detailPlatformStatus": [
        {
          "platformID": 1,
          "connID": "conn_001",
          "isBackground": false,
          "token": "eyJhbGciOiJIUzI1Ni..."
        }
      ]
    },
    {
      "userID": "user_002",
      "status": 0,
      "detailPlatformStatus": []
    }
  ]
}

响应属性列表

参数名	类型	说明
errCode	int	错误码，0 表示成功。
errMsg	string	错误简要信息，成功时为空。
errDlt	errDlt	错误详细信息，成功时为空。
data	array	每个用户的在线状态结果。

data[] 属性

参数名	类型	说明
data[].userID	string	用户 ID。
data[].status	int	在线状态，参见用户模块的 `OnlineStatus`。
data[].detailPlatformStatus	array	用户在线时的终端连接明细。
data[].detailPlatformStatus[].platformID	int	在线终端类型，参见用户模块的 `PlatformID`。
data[].detailPlatformStatus[].connID	string	网关连接 ID。
data[].detailPlatformStatus[].isBackground	bool	该连接是否处于后台状态。
data[].detailPlatformStatus[].token	string	当前连接使用的用户 Token。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1002,
  "errMsg": "NoPermissionError",
  "errDlt": "only app manager"
}

参数名	类型	说明
errCode	int	错误码，具体查看全局错误码文档。
errMsg	string	错误简要信息。
errDlt	errDlt	错误详细信息。

常见错误场景

错误场景	可能原因	处理方式
鉴权失败	请求不是由 APP 管理员发起。	使用 APP 管理员 Token 调用。
返回离线	用户没有连接到任一消息网关。	结合业务在线逻辑判断，不要把离线等同于用户不存在。

这个页面有帮助吗？