/api/long/start

开启长连接。

POST/qingluan/api/long/start

在线调试鉴权与基础约定

接口说明

开启长连接。

:::tip 🔗 调用关系

扫码登录成功 → 配置回调地址 → 开启长连接 → 等待 GapConnected/GapSucceed。 :::

:::warning ⚠️ 调用注意

已连接时会返回 code=-1, message="started"——这是已在运行而非失败，且会重置连接。 :::

:::check ✅ 成功判定：HTTP 200 且响应体 code = 0。业务失败请查看 message 与 detail。 :::

请求参数

请求体必填。通过 QL-Key 请求头携带 APIKey。

Content-Type：application/json

请求参数。字段名区分大小写，请按文档原样传递。

appidstring必填

青鸾实例 ID，形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。

字段示例："we_xxxxxxxxxxxxxxx"

callbackUrlstring必填

回调地址

公网可访问的回调地址，只接受 POST；事件类型见回调包体的 event_type 字段。

注意：只在建连时登记一次。已经连着的时候想换地址，必须用 /api/long/updateCallbackURL；用 start 换会连带重置连接。另外契约 example 里这个值被生成成了 https://example.com/sample.jpg（占位符错误，一张图片地址不可能是回调端点），别照抄，实际要填能接 POST 的接口地址。

字段示例："https://example.com"

pushHistoryboolean必填

是否推送历史消息。true=登录后补推历史，false=只推新消息

注意：未确认。因为没有在「未连接」状态下建过连，true 会补推多少条、补推事件与增量事件在结构上是否有区别，都没有样本。

字段示例：false

响应与结果确认

本接口为能力层原样返回，不统一增加青鸾外层信封。code = 0 仅表示请求被接受，不保证副作用已完成。

请结合业务数据与本页说明判断实际状态，不要仅凭响应码推断操作效果。

响应字段与 HTTP 状态

HTTP 200

能力层原样返回；code = 0 仅表示请求已受理，业务结果须按接口说明确认。

application/json

查看响应字段定义

接口原样返回平台的业务响应。HTTP 状态码与业务状态码需分别判断：HTTP 200 只表示请求已送达，成功以 code = 0 为准。

codeinteger必填

业务状态码

业务状态码：0 表示成功，-1 表示失败；失败原因见 message。

字段示例：0

dataobject可选

业务数据

接口无固定结构化返回数据；成功时通常为空对象或省略 data。

detailstring可选

错误详情

错误详情；无补充信息时通常为空字符串。

messagestring必填

响应消息

业务结果消息。成功通常为 ok；企微错误通常为 错误码|错误信息。

字段示例："ok"

timestring必填

服务端时间

服务端时间，格式为 YYYY-MM-DD HH:mm:ss。

字段示例："2026-07-21 07:33:17"

HTTP 403

受控接口，需通过控制台配置

HTTP 404

appid 不存在或无权访问

请求示例

请求示例 · JSON

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "callbackUrl": "<省略>",
  "pushHistory": false
}

响应示例

HTTP 200 响应示例 · JSON

{
  "code": 0,
  "data": {}
}

本接口为能力层原样返回，不统一增加青鸾外层信封。code = 0 仅表示请求被接受，不保证副作用已完成。

请结合业务数据与本页说明判断实际状态，不要仅凭响应码推断操作效果。