文档中心
即时通讯
服务端 API
用户相关
查询用户在线状态

查询用户在线状态

更新时间：2024-04-10 15:44

描述

查询用户的在线状态，支持查询单个用户、或批量查询多个用户的在线状态。

调用频率限制：20 次/秒

接口原型

请求方法：GET
请求地址：https://zim-api.zego.im/?Action=QueryUserOnlineState
传输协议：HTTPS

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
UserId[]	Array of String	是	需要查询的用户 ID 列表，最大支持查询 100 个用户 ID。示例：UserId[]=a&UserId[]=b

UserId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。

请求示例

https://zim-api.zego.im/?Action=QueryUserOnlineState
&UserId[]=a&UserId[]=b
&<公共请求参数>

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
Result	Object	查询的用户状态结果。用户处于在线状态或离线状态时，通过该字段返回。
UserId	String	在线或离线用户的 ID。
Status	String	用户状态，包括： Online：在线。 Offline：离线。
ErrorList	Object	查询失败列表。用户 ID 不存在或者用户已登出时，通过该字段返回。 Code 为 0： ErrorList 为空，全部用户在线状态查询成功。 ErrorList 不为空，表示部分用户在线状态查询失败，请参考 SubCode 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示所有用户在线状态查询失败。
UserId	String	不存在的用户 ID 或已登出用户的 ID。
SubCode	Number	查询失败时的返回码。

响应示例

{
    "Code":0,
    "Message":"success",
    "RequestId":"343649807833778782",
    "Result": [
      {
          "UserId": "id1",
          "Status": "Offline"
      },
      {
          "UserId": "id2",
          "Status": "Online"
      }
    ],
    "ErrorList": [
      {
          "UserId": "id4",
          "SubCode": 660200001
      }
    ] 
 }

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明
660000011	用户个数超过限制。
660200001	不存在的用户 ID，或者用户已经登出。