青鸾QINGLUAN
控制台

发送小程序卡片

发送小程序卡片。需要小程序 username(gh_ 开头)、appId、path 与封面图。

POST/qingluan/api/message/sendMiniProgram

接口说明

发送小程序卡片。需要小程序 username(gh_ 开头)、appId、path 与封面图。

:::tip 🔗 调用关系

准备小程序信息,并先上传封面图以取得 coverFileIdcoverAesKey 等字段。 :::

:::note 🧩 字段命名:设备标识使用 appid,小程序标识使用 appId,两者区分大小写。 :::

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

请求参数

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

Content-Type:application/json

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

appidstring必填

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

字段示例:"we_xxxxxxxxxxxxxxx"
conversationIdint64必填

会话 ID

会话 ID。群聊传群号,私聊传对方 uin。注意它超出 JavaScript 安全整数范围,JS 侧需按大整数处理,不要经过 Number()

字段示例:7881000000000002
contentobject必填

内容

消息/动态正文。纯文本类接口传字符串;媒体类传对象(把上传接口返回的 data 整体带上)

titlestring必填

标题

标题。用于链接、小程序、朋友圈等卡片展示。

字段示例:"寄快递,用顺丰"
miniProgramDetailsobject必填

契约只列了 3 个字段,需要 9 个。 必填字段是一个一个报出来的——补一个再报下一个,连报 5 轮才补齐。封面相关字段全部来自 /api/cdn/uploadImage 的返回。

usernamestring必填

小程序原始 ID(gh_ 开头)

注意:传伪造值 gh_test 也返回 code=0,平台不校验小程序是否真实存在。因此 code=0 只能证明消息发出,不能证明卡片可点开。

字段示例:"gh_f9d9fca26a50@app"
appIdstring必填

小程序 AppID

小程序 AppID。注意大写 I,不要与设备字段 appid 混用。

字段示例:"wxd4185d00bf7e08ac"
pathstring必填

小程序页面路径

字段示例:"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%"
coverUrlstring可选

缩略图url

字段示例:"https://example.com/sample-media.jpg"
titlestring可选

标题

标题。用于链接、小程序、朋友圈等卡片展示。

字段示例:"寄快递,用顺丰"
appNamestring必填

必填(契约漏标)。不传报 content.miniProgramDetails.appName is required

注意契约漏标的必填项。缺失时平台返回 code=-1content.miniProgramDetails.appName is required。是卡片上显示的小程序名称。

字段示例:"顺丰速运+"
fallbackUrlstring必填

必填(契约漏标)。不传报 content.miniProgramDetails.fallbackUrl is required

注意契约漏标的必填项。缺失时报 content.miniProgramDetails.fallbackUrl is required。语义应为不支持小程序时的降级跳转地址,但未确认降级行为,只验证了必填性。

字段示例:"https://mp.weixin.qq.com/mp/waerrpage?appid=wxd4185d00bf7e08ac&type=upgrade&upgradetype=3#wechat_redirect"
coverFileIdstring必填

必填(契约漏标)。不传报 content.miniProgramDetails.coverFileId is required。值来自 /api/cdn/uploadImage 的返回。

注意契约漏标的必填项,且契约里根本没有这个字段名。取自 /api/cdn/uploadImage 回执的 id。属媒体凭证,落库须加密、日志只记长度。

字段示例:"<sample-media-id>"
coverMd5string必填

必填(契约漏标)。不传报 content.miniProgramDetails.coverMd5 is required。值来自 /api/cdn/uploadImage 的返回。

注意契约漏标的必填项,且契约示例把它的值错写成了一个 URL。实际应是封面图的 32 位 md5,取自图片上传回执。

字段示例:"961aa29ebd964455b22ecfaa691924d7"
coverAesKeystring可选

封面图片的解密密钥,由上传结果提供。

注意:契约未列。与 coverMd5 一起补入,平台从未单独报错要求过它,因此必填性未确认。建议原样透传图片上传回执的 aesKey。属媒体凭证。

字段示例:"caf54890e1a4f45b072e64db3d265fe7"
coverSizeint64可选

封面图片大小,单位为字节。

最小值:0 字段示例:57102
coverWidthint64必填

必填(契约漏标)。不传报 content.miniProgramDetails.coverWidth and coverHeight are required

注意契约漏标的必填项。它与 coverHeight 由平台在同一条报错里一起要求coverWidth and coverHeight are required),必须成对提供。

最小值:0 字段示例:500
coverHeightint64必填

必填(契约漏标)。不传报 content.miniProgramDetails.coverWidth and coverHeight are required

注意契约漏标的必填项,与 coverWidth 成对,见上。

最小值:0 字段示例:400

响应与结果确认

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

发送后通过拉取消息复核。超时或网络中断时,先确认结果,再决定是否重试,避免重复消息。

响应字段与 HTTP 状态

HTTP 200

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

application/json

查看响应字段定义

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

codeinteger必填

业务状态码

业务状态码:0 表示成功,-1 表示失败;失败原因见 message

字段示例:0
dataobject可选

业务数据

业务返回数据;字段结构见下方定义。

idint64可选

对象 ID。发消息返回时即 serverMsgId(撤回要用);上传返回时即 fileId(发送/下载要用);列表项中为该条记录 ID

syncKeyint64可选

同步游标

同步键。下次增量同步传回

messageTypeint64可选

消息类型枚举(0=普通消息)

fromUserIdint64可选

发送方 ID

toUserIdint64可选

接收方 ID

roomIdint64可选

群聊 ID

群聊 ID。可从创建群、群列表、群详情或回调事件中获取。

contentTypeint64可选

内容类型。0=文本 14=图片(完整枚举见平台「企微错误码」章节)

sendTimeint64可选

发送时间戳(秒)

appInfostring可选

企微内部应用标识,透传字段,无需处理

senderNamestring可选

消息发送名称

contentobject可选

内容

消息/动态正文。纯文本类接口传字符串;媒体类传对象(把上传接口返回的 data 整体带上)

titlestring可选

标题

标题。用于链接、小程序、朋友圈等卡片展示。

miniProgramDetailsobject可选

小程序卡片详情

usernamestring可选

小程序原始 ID(gh_ 开头)

appIdstring可选

小程序 AppID

小程序 AppID。注意大写 I,不要与设备字段 appid 混用。

pathstring可选

小程序页面路径

typeint64可选

类型

小程序卡片类型枚举值,由平台定义。

sourceint64可选

来源名称。sendLink 必填,缺失会报 content.source is required

coverUrlstring可选

缩略图url

titlestring可选

标题

标题。用于链接、小程序、朋友圈等卡片展示。

appNamestring可选

小程序名称。

fallbackUrlstring可选

小程序备用网页地址。

appNameDupstring可选

服务端返回的小程序名称副本字段;兼容字段,原样保留。

coverMd5string可选

封面图片的 MD5 校验值。

coverSizeint64可选

封面图片大小,单位为字节。

最小值:0
reserved19int64可选

平台保留字段 19,当前无公开枚举说明。

reserved20int64可选

平台保留字段 20,当前无公开枚举说明。

coverWidthint64可选

封面图片宽度,单位为像素。

最小值:0
coverHeightint64可选

封面图片高度,单位为像素。

最小值:0
flagint64可选

状态标志位(按位含义见平台文档)

detailstring可选

错误详情

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

messagestring必填

响应消息

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

字段示例:"ok"
timestring必填

服务端时间

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

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

HTTP 403

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

HTTP 404

appid 不存在或无权访问

搜索接口

输入关键词查找接口。最多显示 20 项。