请求地址
POST https://api.qingluanbot.com/qingluan/api/message/sendMiniProgram
请求示例
curl -X POST 'https://api.qingluanbot.com/qingluan/api/message/sendMiniProgram' \
-H 'X-Qingluan-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ql_appid": "inst_xxxxxxxxxxxx",
"conversationId": 7881301709020163,
"content": {
"title": "寄快递，用顺丰",
"miniProgramDetails": {
"username": "gh_f9d9fca26a50@app",
"appId": "wxd4185d00bf7e08ac",
"path": "pages/tabBar/index/index.html?sampshare=%7B%22i%22%3A%22oXJy05GA6HNgF5vZ1hY7ATHaidZY%22%2C%22p%22%3A%22pages%2FtabBar%2Findex%2Findex%22%2C%22d%22%3A0%2C%22m%22%3A%22%E8%BD%AC%E5%8F%91%E6%B6%88%E6%81%",
"coverUrl": "https://example.com/sample-media.jpg",
"title": "寄快递，用顺丰",
"appName": "顺丰速运+",
"fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=wxd4185d00bf7e08ac&type=upgrade&upgradetype=3#wechat_redirect",
"coverFileId": "<sample-media-id>",
"coverMd5": "961aa29ebd964455b22ecfaa691924d7",
"coverAesKey": "caf54890e1a4f45b072e64db3d265fe7",
"coverSize": 57102,
"coverWidth": 500,
"coverHeight": 400
}
}
}'
请求参数
| 字段 | 类型 | 要求 | 说明 |
|---|
ql_appid | string | 必填 | 青鸾实例 ID，形如 inst_xxxx。在开发者控制台「实例与回调」扫码上号后获得。 |
conversationId | integer | 必填 | 会话 ID。群聊传群号，私聊传对方 uin。注意它超出 JavaScript 安全整数范围，JS 侧需按大整数处理，不要经过 Number()。 |
content | object | 必填 | 消息/动态正文。纯文本类接口传字符串；媒体类传对象（把上传接口返回的 data 整体带上） |
响应判断
能力层接口返回包含 code、message、time 与 data 等字段；请以 code=0 判断业务成功。HTTP 200 只表示网关已返回响应，不能替代业务状态判断。
可能的响应状态
| HTTP 状态 | 公开契约说明 |
|---|
200 | 原样返回（code = 0 即成功） |
403 | 受控接口，需通过控制台配置 |
404 | ql_appid 不存在或无权访问 |
200 响应示例
{
"code": 0,
"data": {
"id": 0,
"syncKey": 0,
"messageType": 0,
"fromUserId": 0,
"toUserId": 0,
"roomId": 0,
"contentType": 0,
"sendTime": 0,
"appInfo": "请按接口说明填写",
"senderName": "请按接口说明填写",
"content": {
"title": "请按接口说明填写",
"miniProgramDetails": {
"username": "请按接口说明填写",
"appId": "REPLACE_WITH_ID",
"path": "请按接口说明填写",
"type": 0,
"source": 0,
"coverUrl": "https://your.app/qingluan/callback",
"title": "请按接口说明填写",
"appName": "请按接口说明填写",
"fallbackUrl": "https://your.app/qingluan/callback",
"appNameDup": "请按接口说明填写",
"coverMd5": "请按接口说明填写",
"coverSize": 0,
"reserved19": 0,
"reserved20": 0,
"coverWidth": 0,
"coverHeight": 0,
"flag": 0
}
}
},
"detail": "请按接口说明填写",
"message": "ok",
"time": "2026-07-21 07:33:17"
}
接入步骤
- 在青鸾开发者控制台创建或查看 API Key。
- 在「实例与回调」接入企业微信账号，取得
ql_appid。 - 请求头携带
X-Qingluan-Key，按当前契约提交 JSON 请求。 - 读取响应中的
code；仅当 code=0 时按成功流程处理。