功能说明
获取用户当前的登录状态。
接口调用说明
请求 URL 示例
https://xxxxxx/v4/openim/query_online_status?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
请求参数说明
参数 | 说明 |
xxxxxx | SDKAppID 所在国家/地区对应的专属域名： 中国： console.tim.qq.com新加坡： adminapisgp.im.qcloud.com首尔： adminapikr.im.qcloud.com法兰克福： adminapiger.im.qcloud.com硅谷： adminapiusa.im.qcloud.com雅加达： adminapiidn.im.qcloud.com |
v4/openim/query_online_status | 请求接口 |
sdkappid | 创建应用时即时通信 IM 控制台分配的 SDKAppID |
identifier | |
usersig | |
random | 请输入随机的32位无符号整数，取值范围0 - 4294967295 |
contenttype | 请求格式固定值为 json |
请求频率限制
默认接口请求频率限制：200次/秒。
注意：
请求包示例
无需获取详细的登录平台信息
{"To_Account": ["id1", "id2", "id3", "id4"]}
需要获取详细的登录平台信息
{"IsNeedDetail": 1,"To_Account": ["id1", "id2", "id4"]}
请求包字段说明
字段 | 类型 | 属性 | 说明 |
To_Account | Array | 必填 | 需要查询这些 UserID 的登录状态，一次最多查询500个 UserID 的状态。 |
IsNeedDetail | Integer | 选填 | 是否需要返回详细的登录平台信息： 0：表示不需要。 1：表示需要。 |
IsReturnCustomStatus | Integer | 选填 | 是否需要返回这些 UserID 的自定义状态： 0：表示不需要。 1：表示需要。 |
应答包体示例
无需获取详细的登录平台信息
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"QueryResult": [{"To_Account": "id1","Status": "Offline"},{"To_Account": "id2","Status": "Online"},{"To_Account": "id3","Status": "PushOnline"}],"ErrorList": [{"To_Account": "id4","ErrorCode": 70107}]}
需要获取详细的登录平台信息
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"QueryResult": [{"To_Account": "id1","Status": "Online","Detail": [{"Platform": "iPhone","Status": "PushOnline""IsBackground": 1,"Instid": 74224656,"CustomIdentifier": "device-1"},{"Platform": "Web","Status": "Online","IsBackground": 1,"Instid": 74224656,"CustomIdentifier": "device-2"}]},{"To_Account": "id2","Status": "Offline",}],"ErrorList": [{"To_Account": "id4","ErrorCode": 70107}]}
请求出错
{"ActionStatus": "FAIL","ErrorInfo": "Fail to Parse json data of body, Please check it","ErrorCode": 90001}
应答包字段说明
字段 | 类型 | 说明 |
ActionStatus | String | 请求处理的结果： OK：表示处理成功。 FAIL：表示失败。 |
ErrorInfo | String | 详细错误信息。 |
ErrorCode | Integer | 本次请求的错误码： 如有任意账号查询状态成功，则此字段返回0。 全部账号都查询失败，则此字段返回非0。 |
QueryResult | Array | 返回的用户在线状态结构化信息。 |
QueryResult.To_Account | String | 返回的用户的 UserID。 |
QueryResult.Status | String | 返回的用户状态，目前支持的状态有： 前台运行状态（Online）：客户端登录后和即时通信 IM 后台有长连接。 后台运行状态（PushOnline）：iOS 和 Android 进程被 kill 或因网络问题掉线，进入 PushOnline 状态，此时仍然可以接收消息的离线推送。客户端切到后台，但是进程未被手机操作系统 kill 掉时，此时状态仍是 Online。 未登录状态（Offline）：客户端主动退出登录或者客户端自上一次登录起7天之内未登录过。 如果用户是多终端登录，则只要有一个终端的状态是 Online ，该字段值就是 Online。 |
QueryResult.CustomStatus | String | 返回的用户的自定义状态。 |
QueryResult.Detail | Object | 详细的登录平台信息。 |
QueryResult.Detail.Platform | String | 登录的平台类型。可能的返回值有："iPhone", "Android", "Web", "PC", "iPad", "Mac"。 |
QueryResult.Detail.Status | String | 该登录平台的状态。 |
QueryResult.Detail.Instid | Integer | 设备唯一 ID。 |
QueryResult.Detail.CustomIdentifier | String | 客户自定义设备标识。 |
QueryResult.Detail.IsBackground | Integer | 该登录平台的前后台状态： 0：该设备处于前台。 1：该设备处于后台。 |
ErrorList | Array | 状态查询失败的账号列表，在此列表中的目标账号，状态查询失败或目标账号不存在。若状态全部查询成功，则 ErrorList 为空。 |
ErrorList.To_Account | String | 状态查询失败的目标账号。 |
ErrorList.ErrorCode | Integer | 状态查询失败的错误码，若目标账号的错误码为70107，表示该账号不存在。 |
注意：
即时通信 IM 后台只会保存 PushOnline 状态7天时间，若从掉线时刻起7天之内未登录过，则进入 Offline 状态。
若集成了推送服务（Push），PushOnline 状态会保存30天。
错误码说明
除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码、错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码 | 含义说明 |
70107 | 请求的用户账号不存在 |
70169 | 服务端内部超时，请稍后重试 |
90001 | JSON 格式解析失败，请检查请求包是否符合 JSON 规范。或者 To_Account 是空数组 |
90003 | JSON 格式请求包中 To_Account 不符合消息格式描述，请检查 To_Account 类型是否为 String |
90009 | 请求需要 App 管理员权限 |
90011 | 批量发消息目标账号超过500，请减少 To_Account 中目标账号数量 |
90992 | 后端服务超时，请重试 |
90994 | 服务内部错误，请重试 |
90995 | 服务内部错误，请重试 |
91000 | 服务内部错误，请重试 |
接口调试工具
参考
失效账号登录态（v4/im_open_login_svc/kick）
