查询微信扫码会话
curl --request GET \
--url https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key} \
--header 'Authorization: Bearer <token>' \
--header 'zai-beta: <zai-beta>' \
--header 'zai-version: <zai-version>'import requests
url = "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}"
headers = {
"zai-version": "<zai-version>",
"zai-beta": "<zai-beta>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'zai-version': '<zai-version>',
'zai-beta': '<zai-beta>',
Authorization: 'Bearer <token>'
}
};
fetch('https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}")
.header("zai-version", "<zai-version>")
.header("zai-beta", "<zai-beta>")
.header("Authorization", "Bearer <token>")
.asString();package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("zai-version", "<zai-version>")
req.Header.Add("zai-beta", "<zai-beta>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"zai-beta: <zai-beta>",
"zai-version: <zai-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"type": "channel_qr_session",
"session_key": "chqr_xxx",
"channel_id": "channel_wechat_xxx",
"provider": "wechat",
"status": "confirmed",
"qr_code": null,
"expires_at": "2026-10-30T00:08:00.000Z",
"confirmed_at": "2026-10-30T00:01:00.000Z",
"created_at": "2026-10-30T00:00:00.000Z",
"updated_at": "2026-10-30T00:01:00.000Z"
}{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "请求字段或类型不合法。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "not_found_error",
"message": "资源不存在、已删除或不属于当前账号。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "账号或全局请求频率超限。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "api_error",
"message": "扫码查询依赖暂时不可用。",
"details": {}
},
"request_id": "req_xxx"
}Channel
查询微信扫码会话
查询当前账号、本 Channel 的公开微信扫码会话。成功返回 200;会话不属于当前账号或指定 Channel 时返回 404。
GET
/
agent
/
forward
/
v0
/
channels
/
{channelId}
/
qr-sessions
/
{session_key}
查询微信扫码会话
curl --request GET \
--url https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key} \
--header 'Authorization: Bearer <token>' \
--header 'zai-beta: <zai-beta>' \
--header 'zai-version: <zai-version>'import requests
url = "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}"
headers = {
"zai-version": "<zai-version>",
"zai-beta": "<zai-beta>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'zai-version': '<zai-version>',
'zai-beta': '<zai-beta>',
Authorization: 'Bearer <token>'
}
};
fetch('https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}")
.header("zai-version", "<zai-version>")
.header("zai-beta", "<zai-beta>")
.header("Authorization", "Bearer <token>")
.asString();package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("zai-version", "<zai-version>")
req.Header.Add("zai-beta", "<zai-beta>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/{channelId}/qr-sessions/{session_key}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"zai-beta: <zai-beta>",
"zai-version: <zai-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"type": "channel_qr_session",
"session_key": "chqr_xxx",
"channel_id": "channel_wechat_xxx",
"provider": "wechat",
"status": "confirmed",
"qr_code": null,
"expires_at": "2026-10-30T00:08:00.000Z",
"confirmed_at": "2026-10-30T00:01:00.000Z",
"created_at": "2026-10-30T00:00:00.000Z",
"updated_at": "2026-10-30T00:01:00.000Z"
}{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "请求字段或类型不合法。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "not_found_error",
"message": "资源不存在、已删除或不属于当前账号。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "账号或全局请求频率超限。",
"details": {}
},
"request_id": "req_xxx"
}{
"type": "error",
"error": {
"type": "api_error",
"message": "扫码查询依赖暂时不可用。",
"details": {}
},
"request_id": "req_xxx"
}沿用 Channel API 的 Bearer 认证、
正常状态流为 waiting → scanned → confirmed;也可能过期(expired)、被拒绝(denied)或出错(error)。
重新创建扫码会话;完整流程见接入个人微信。
zai-version: 2026-05-26 和 zai-beta: managed-agents-2026-05-26;多个 beta 值用逗号分隔且必须包含此值。发送 JSON 时设 Content-Type: application/json。扫码 POST / GET 分别计入 write / read 限流。
状态与响应字段
| 字段 | 说明 |
|---|---|
type | 固定 channel_qr_session |
session_key | 扫码会话 ID |
channel_id | 所属 Channel |
provider | 固定 wechat |
status | waiting / scanned / confirmed / expired / denied / error |
qr_code | PNG data URL;仅有效 waiting/scanned 状态可用,终态或过期后 null |
expires_at | 过期时间,当前约 8 分钟,以此字段为准 |
confirmed_at | 手机端确认时间或 null |
created_at / updated_at | 时间戳 |
error | 仅 error 状态可能返回的安全提示 |
scanned 只表示已扫码,不表示确认成功。由计划绑定的微信用户扫码并在手机确认,轮询到 confirmed 后,再调用获取 Channel确认 binding_status=bound 与 connection_status=connected。
新建二维码使旧扫码会话失效;已有绑定以服务端确认状态为准。重建 WeChat Channel 后必须重新扫码,不能导入旧 bot token,也不能绕过微信安全验证。二维码只交给计划绑定账号的持有人,不要发送到群聊或共享文档。响应示例使用确认后的终态,不包含真实二维码。
请求示例
curl --request GET "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/$CHANNEL_ID/qr-sessions/$QR_SESSION_KEY" \
--header "Authorization: Bearer $ZHIPUAI_API_KEY" \
--header "zai-version: 2026-05-26" \
--header "zai-beta: managed-agents-2026-05-26"
Headers
Channel API v0 基础协议标识,固定为 2026-05-26。
Available options:
2026-05-26 Example:
"2026-05-26"
可有多个逗号分隔值,但必须包含 managed-agents-2026-05-26。
Example:
"managed-agents-2026-05-26"
Path Parameters
当前账号的 WeChat Channel ID。
Example:
"channel_wechat_xxx"
本 Channel 扫码会话 ID。
Example:
"chqr_xxx"
Response
扫码会话详情。
固定资源类型。
Available options:
channel_qr_session 扫码会话 ID。
Example:
"chqr_xxx"
所属 Channel。
Example:
"channel_wechat_xxx"
固定 wechat。
Available options:
wechat scanned 只表示已扫码;confirmed 表示手机端确认成功,仍需查询 Channel 状态。
Available options:
waiting, scanned, confirmed, expired, denied, error PNG data URL,仅有效 waiting/scanned 状态返回;终态或过期为 null。不要公开到群聊或共享文档。
约 8 分钟,以此过期时间为准。
确认时间,未确认时为 null。
创建时间。
更新时间。
仅 error 状态可能返回的安全错误提示。
Was this page helpful?