> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建微信扫码会话

> 创建个人微信扫码会话。Body 只能为空或 {}，其他内容返回 400。成功返回 201；不能给非 WeChat Channel 创建二维码，返回 409。

沿用 Channel API 的 Bearer 认证、`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 状态可能返回的安全提示 |

正常状态流为 waiting → scanned → confirmed；也可能过期（expired）、被拒绝（denied）或出错（error）。`scanned` 只表示已扫码，不表示确认成功。由计划绑定的微信用户扫码并在手机确认，轮询到 confirmed 后，再调用[获取 Channel](https://docs.bigmodel.cn/api-reference/channel/get.md)确认 `binding_status=bound` 与 `connection_status=connected`。

新建二维码使旧扫码会话失效；已有绑定以服务端确认状态为准。重建 WeChat Channel 后必须重新扫码，不能导入旧 bot token，也不能绕过微信安全验证。二维码只交给计划绑定账号的持有人，不要发送到群聊或共享文档。响应示例的二维码数据用 xxx 占位，不能用于扫码。

## 请求示例

```bash
curl --request POST "https://agent-api.bigmodel.cn/api/agent/forward/v0/channels/$CHANNEL_ID/qr-sessions" \
  --header "Authorization: Bearer $ZHIPUAI_API_KEY" \
  --header "zai-version: 2026-05-26" \
  --header "zai-beta: managed-agents-2026-05-26" \
  --header "Content-Type: application/json" \
  --data '{}'
```

[下一步：查询扫码会话](https://docs.bigmodel.cn/api-reference/channel/qr-get.md)；完整流程见[接入个人微信](https://docs.bigmodel.cn/cn/managed-agents/channels.md#接入个人微信)。


## OpenAPI

````yaml /openapi/openapi-channel.json post /agent/forward/v0/channels/{channelId}/qr-sessions
openapi: 3.0.1
info:
  title: Channel API
  version: '2026-10-30'
  description: >-
    Channel API v0：将固定版本的 Agent
    接入飞书、企业微信、钉钉和个人微信。提供创建、分页查询、详情、有限配置更新、删除以及微信扫码会话创建和查询。连接异步建立；201 仅表示配置保存成功。
servers:
  - url: https://agent-api.bigmodel.cn/api
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: Channel
    description: 渠道管理；Agent 运行仍通过 Managed Session 和 Events API。
paths:
  /agent/forward/v0/channels/{channelId}/qr-sessions:
    post:
      tags:
        - Channel
      summary: 创建微信扫码会话
      description: >-
        创建个人微信扫码会话。Body 只能为空或 {}，其他内容返回 400。成功返回 201；不能给非 WeChat Channel
        创建二维码，返回 409。
      operationId: forwardPostChannelQrSession
      parameters:
        - $ref: '#/components/parameters/ForwardZaiVersion'
        - $ref: '#/components/parameters/ForwardZaiBeta'
        - name: channelId
          in: path
          required: true
          schema:
            type: string
            example: channel_wechat_xxx
          description: 当前账号的 WeChat Channel ID。
      requestBody:
        required: false
        description: 只允许空 body 或 {}；其他内容返回 400。
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
            example: {}
      responses:
        '201':
          description: 扫码会话创建成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelQrSession'
              example:
                type: channel_qr_session
                session_key: chqr_xxx
                channel_id: channel_wechat_xxx
                provider: wechat
                status: waiting
                qr_code: data:image/png;base64,xxx
                expires_at: '2026-10-30T00:08:00.000Z'
                confirmed_at: null
                created_at: '2026-10-30T00:00:00.000Z'
                updated_at: '2026-10-30T00:00:00.000Z'
        '400':
          description: 请求字段或类型不合法。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: invalid_request_error
                  message: 请求字段或类型不合法。
                  details: {}
                request_id: req_xxx
        '404':
          description: 资源不存在、已删除或不属于当前账号。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: not_found_error
                  message: 资源不存在、已删除或不属于当前账号。
                  details: {}
                request_id: req_xxx
        '409':
          description: 只有 WeChat Channel 支持创建扫码会话。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: conflict_error
                  message: 只有 WeChat Channel 支持创建扫码会话。
                  details: {}
                request_id: req_xxx
        '429':
          description: 账号或全局请求频率超限。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: rate_limit_error
                  message: 账号或全局请求频率超限。
                  details: {}
                request_id: req_xxx
          headers:
            retry-after:
              description: 建议等待的相对秒数。503 并发预检忙时可为 1。
              schema:
                type: string
            ratelimit-limit:
              description: 当前桶容量。
              schema:
                type: string
            ratelimit-remaining:
              description: 剩余容量，拒绝时为 0。
              schema:
                type: string
            ratelimit-reset:
              description: 恢复一个请求额度所需的相对秒数。
              schema:
                type: string
            x-ratelimit-scope:
              description: 仅全局限流时返回 global。
              schema:
                type: string
        '502':
          description: 二维码响应无效或渲染异常。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: api_error
                  message: 二维码响应无效或渲染异常。
                  details: {}
                request_id: req_xxx
        '503':
          description: 二维码服务或依赖不可用。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardAgentErrorResponse'
              example:
                type: error
                error:
                  type: api_error
                  message: 二维码服务或依赖不可用。
                  details: {}
                request_id: req_xxx
          headers:
            retry-after:
              description: 建议等待的相对秒数。503 并发预检忙时可为 1。
              schema:
                type: string
components:
  parameters:
    ForwardZaiVersion:
      name: zai-version
      in: header
      required: true
      description: Channel API v0 基础协议标识，固定为 2026-05-26。
      schema:
        type: string
        enum:
          - '2026-05-26'
        default: '2026-05-26'
        example: '2026-05-26'
    ForwardZaiBeta:
      name: zai-beta
      in: header
      required: true
      description: 可有多个逗号分隔值，但必须包含 managed-agents-2026-05-26。
      schema:
        type: string
        default: managed-agents-2026-05-26
        example: managed-agents-2026-05-26
  schemas:
    ChannelQrSession:
      type: object
      properties:
        type:
          type: string
          description: 固定资源类型。
          enum:
            - channel_qr_session
        session_key:
          type: string
          description: 扫码会话 ID。
          example: chqr_xxx
        channel_id:
          type: string
          description: 所属 Channel。
          example: channel_wechat_xxx
        provider:
          type: string
          description: 固定 wechat。
          enum:
            - wechat
        status:
          type: string
          description: scanned 只表示已扫码；confirmed 表示手机端确认成功，仍需查询 Channel 状态。
          enum:
            - waiting
            - scanned
            - confirmed
            - expired
            - denied
            - error
        qr_code:
          type: string
          description: PNG data URL，仅有效 waiting/scanned 状态返回；终态或过期为 null。不要公开到群聊或共享文档。
          nullable: true
        expires_at:
          type: string
          description: 约 8 分钟，以此过期时间为准。
          format: date-time
        confirmed_at:
          type: string
          description: 确认时间，未确认时为 null。
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          description: 创建时间。
        updated_at:
          type: string
          format: date-time
          description: 更新时间。
        error:
          type: object
          nullable: true
          additionalProperties: true
          description: 仅 error 状态可能返回的安全错误提示。
      required:
        - type
        - session_key
        - channel_id
        - provider
        - status
        - qr_code
        - expires_at
        - confirmed_at
        - created_at
        - updated_at
      additionalProperties: false
      example:
        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'
    ForwardAgentErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - error
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - permission_error
                - invalid_request_error
                - not_found_error
                - conflict_error
                - rate_limit_error
                - api_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - type
            - message
            - details
          additionalProperties: false
        request_id:
          type: string
          example: req_xxx
      required:
        - type
        - error
        - request_id
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        标准的 HTTP Bearer 认证方式，在 [API
        Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 页面获取密钥。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.