查询实例登录状态

读取平台侧记录的实例登录状态。适合在后台展示实例状态，或在发送消息前做一次粗筛。

接口地址： POST /isOnline

这不是实时在线探测

本接口返回的是平台保存的登录记录是否存在，不会向微信客户端发起实时探测。

微信在客户端被踢下线、网络异常断开等情况下，平台需要通过重连与对账流程才能确认失联并清除该记录， 因此 data.isOnline 存在延迟收敛：不同异常路径的收敛时间不同，期间可能仍返回 true。

发送消息前的校验只能挡住已确认离线的实例，不能保证实例此刻在线。真实结果以发送接口的返回为准。

说明

接口调用成功（code = 1000）不等于实例在线。登录状态以 data.isOnline 为准。

请求参数

参数名	必选	类型	说明
wId	是	string	登录实例标识

响应参数

参数名	类型	说明
code	string	1000 成功；其他值都是失败，通常是 1001
message	string	反馈信息
data.isOnline	boolean	true 平台存在该实例的登录记录，false 不存在(已确认离线)

请求示例

HTTP

POST {BASE_URL}/isOnline
Authorization: Bearer <你的调用凭证>
Content-Type: application/json

{
 "wId": "0000016e-abcd-0ea8-0002-d8c2dfdb0bf3"
}

curl

curl -X POST '{BASE_URL}/isOnline' \
  -H 'Authorization: Bearer <你的调用凭证>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
 "wId": "0000016e-abcd-0ea8-0002-d8c2dfdb0bf3"
}'

Python

import requests

url = "{BASE_URL}/isOnline"
headers = {"Authorization": "Bearer <你的调用凭证>", "Content-Type": "application/json"}
body = """{
 "wId": "0000016e-abcd-0ea8-0002-d8c2dfdb0bf3"
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/isOnline";
String body = "{\n" +
    " \"wId\": \"0000016e-abcd-0ea8-0002-d8c2dfdb0bf3\"\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的调用凭证>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

PHP

<?php

$url = '{BASE_URL}/isOnline';
$body = <<<'JSON'
{
 "wId": "0000016e-abcd-0ea8-0002-d8c2dfdb0bf3"
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的调用凭证>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

存在登录记录

{
 "message": "成功",
 "code": "1000",
 "data": {
 "isOnline": true
 }
}

无登录记录

{
 "message": "成功",
 "code": "1000",
 "data": {
 "isOnline": false
 }
}

错误响应

{
 "message": "失败",
 "code": "1001",
 "data": null
}

使用建议

• 发送前主动检查，用本接口。
• 实时感知掉线，接入消息回调。
• 查询为离线时，确认网络后可继续调用 断线重连。