appidstring必填青鸾实例 ID,形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。
"we_xxxxxxxxxxxxxxx"发送小程序卡片。需要小程序 username(gh_ 开头)、appId、path 与封面图。
/qingluan/api/message/sendMiniProgram发送小程序卡片。需要小程序 username(gh_ 开头)、appId、path 与封面图。
:::tip 🔗 调用关系
准备小程序信息,并先上传封面图以取得 coverFileId、coverAesKey 等字段。 :::
:::note 🧩 字段命名:设备标识使用 appid,小程序标识使用 appId,两者区分大小写。 :::
:::check ✅ 成功判定:HTTP 200 且响应体 code = 0。业务失败请查看 message 与 detail。 :::
请求体必填。通过 QL-Key 请求头携带 APIKey。
Content-Type:application/json
请求参数。字段名区分大小写,请按文档原样传递。
appidstring必填青鸾实例 ID,形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。
"we_xxxxxxxxxxxxxxx"conversationIdint64必填会话 ID
会话 ID。群聊传群号,私聊传对方 uin。注意它超出 JavaScript 安全整数范围,JS 侧需按大整数处理,不要经过 Number()。
7881000000000002contentobject必填内容
消息/动态正文。纯文本类接口传字符串;媒体类传对象(把上传接口返回的 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=-1、content.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
字段示例:57102coverWidthint64必填必填(契约漏标)。不传报 content.miniProgramDetails.coverWidth and coverHeight are required。
注意:契约漏标的必填项。它与 coverHeight 由平台在同一条报错里一起要求(coverWidth and coverHeight are required),必须成对提供。
0
字段示例:500coverHeightint64必填必填(契约漏标)。不传报 content.miniProgramDetails.coverWidth and coverHeight are required。
注意:契约漏标的必填项,与 coverWidth 成对,见上。
0
字段示例:400本接口为能力层原样返回,不统一增加青鸾外层信封。code = 0 仅表示请求被接受,不保证副作用已完成。
发送后通过拉取消息复核。超时或网络中断时,先确认结果,再决定是否重试,避免重复消息。
能力层原样返回;code = 0 仅表示请求已受理,业务结果须按接口说明确认。
application/json
接口原样返回平台的业务响应。HTTP 状态码与业务状态码需分别判断:HTTP 200 只表示请求已送达,成功以 code = 0 为准。
codeinteger必填业务状态码
业务状态码:0 表示成功,-1 表示失败;失败原因见 message。
0dataobject可选业务数据
业务返回数据;字段结构见下方定义。
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可选封面图片大小,单位为字节。
最小值:0reserved19int64可选平台保留字段 19,当前无公开枚举说明。
reserved20int64可选平台保留字段 20,当前无公开枚举说明。
coverWidthint64可选封面图片宽度,单位为像素。
最小值:0coverHeightint64可选封面图片高度,单位为像素。
最小值:0flagint64可选状态标志位(按位含义见平台文档)
detailstring可选错误详情
错误详情;无补充信息时通常为空字符串。
messagestring必填响应消息
业务结果消息。成功通常为 ok;企微错误通常为 错误码|错误信息。
"ok"timestring必填服务端时间
服务端时间,格式为 YYYY-MM-DD HH:mm:ss。
"2026-07-21 07:33:17"受控接口,需通过控制台配置
appid 不存在或无权访问