微信发送小程序卡片消息接口

前言

在私域流量运营中，小程序卡片消息是转化率最高的消息类型之一——用户点击即跳转落地页，无需二次搜索。然而微信官方限制个人号直接调用小程序发送接口，企业开发者若想通过个人微信账号批量或自动化发送小程序卡片，往往卡在协议层无从下手。本文系统梳理小程序卡片消息的结构、发送流程、接口参数及实战示例，并介绍如何借助 WechatApi 个人微信API 实现稳定可靠的小程序卡片推送。

小程序卡片消息的结构与显示效果

微信小程序卡片消息（MiniApp Card Message）在聊天窗口中以独立卡片形式呈现，包含以下视觉元素：

与普通文本、图片消息相比，小程序卡片消息的点击转化路径最短：用户点击卡片 → 直接进入小程序指定页面。这一特性让它在电商促销、服务预约、活动报名等场景中备受青睐。

从微信协议层看，小程序卡片消息属于 appmsg 类型（type=33），消息体为 XML 结构，需要正确填充 weappinfo 节点，包含 username（小程序原始ID）、appid（appid）、pagepath（页面路径）以及封面图的 cdn key。手动构造这套 XML 并通过个人微信账号发出，是有一定门槛的事情，这也是为什么大多数开发者选择成熟的 微信iPad协议 封装方案来完成这项工作。

为什么个人微信发小程序卡片比较特殊

微信官方开放平台的"客服消息"接口允许公众号/小程序给用户发小程序卡片，但前提是用户必须先触发客服会话（48小时窗口期），且只能发给关注者或近期有交互的用户，无法主动触达任意微信好友。

个人微信账号在日常使用中是可以手动发送小程序卡片的（从小程序内分享、或聊天框转发），但通过常规 Web/PC 协议自动化发送时，微信对此类消息有严格的格式和签名校验。若格式不符或签名错误，消息会被静默丢弃，接收方什么都看不到，排查极为困难。

WechatApi 基于 iPad 协议实现个人微信的消息收发，封装了小程序卡片消息的完整构造与发送逻辑，开发者只需通过 HTTP POST 传入必要的业务参数即可完成发送，无需关心底层 XML 拼装和协议签名细节。这是 微信二次开发 中常见的做法：通过 API 网关屏蔽协议复杂度，专注业务逻辑。

接口调用前的准备工作

在调用小程序卡片消息接口之前，需要完成以下准备步骤：

1. 注册并获取 API 凭证

前往 WechatApi 控制台 注册账号，创建设备后获得：

• VideosApi-token：请求鉴权 Token，放在 HTTP Header 中
• appId：设备ID，标识当前登录的微信账号实例，放在请求 Body 中

2. 登录个人微信账号

在控制台完成设备绑定，扫码登录目标个人微信账号。登录成功后设备状态变为「在线」，此后的接口调用均以该账号身份发出消息。

3. 准备小程序信息

需要提前获取目标小程序的以下信息：

• 小程序原始ID（username）：形如 gh_xxxxxxxx，在小程序管理后台「基本设置」中可见
• 小程序AppID：形如 wx_xxxxxxxx
• 页面路径（pagepath）：具体要跳转的页面及参数，如 /pages/product/detail?id=888
• 封面图URL：用于展示的卡片封面图，建议使用 CDN 加速地址

4. 确认接收方 wxid

接收方必须是当前账号的微信好友或已在的群聊，获取接收方的 wxid（个人好友）或 chatroom_id（群聊）。

接口参数详解

请求规范

响应体结构

接口统一返回 JSON，字段含义如下：

json{
  "ret": 200,
  "msg": "发送成功",
  "data": {
    "msgId": "7380123456789012345",
    "createTime": 1718200000,
    "toWxid": "wxid_xxxxxxxxxx"
  }
}

• ret：状态码，200 表示成功，其他值为错误码
• msg：状态描述，失败时包含错误原因
• data.msgId：消息唯一ID，可用于后续消息撤回或追踪
• data.createTime：消息发送时间戳（秒级 Unix 时间）

常见错误码参考：

代码示例

Python 示例

pythonimport requests

# 接口地址（示意，实际以控制台文档为准）
API_URL = "https://api.wechatapi.net/v1/message/miniapp-card"

# 鉴权 Token 和设备ID从控制台获取
TOKEN = "your_videos_api_token_here"
APP_ID = "your_device_app_id_here"

headers = {
    "VideosApi-token": TOKEN,
    "Content-Type": "application/json"
}

payload = {
    "appId": APP_ID,
    "toWxid": "wxid_xxxxxxxxxx",          # 接收方 wxid
    "miniAppId": "wx1234567890abcdef",     # 小程序 AppID
    "miniAppUsername": "gh_abcdef123456",  # 小程序原始ID
    "pagePath": "/pages/product/detail?id=888&source=wechat",
    "title": "限时特惠，立减50元",
    "coverUrl": "https://cdn.example.com/miniapp-cover.jpg"
}

response = requests.post(API_URL, json=payload, headers=headers)
result = response.json()

if result.get("ret") == 200:
    msg_id = result["data"]["msgId"]
    print(f"发送成功，消息ID：{msg_id}")
else:
    print(f"发送失败：{result.get('msg')}")

cURL 示例

bashcurl -X POST "https://api.wechatapi.net/v1/message/miniapp-card" \
  -H "VideosApi-token: your_videos_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your_device_app_id_here",
    "toWxid": "wxid_xxxxxxxxxx",
    "miniAppId": "wx1234567890abcdef",
    "miniAppUsername": "gh_abcdef123456",
    "pagePath": "/pages/product/detail?id=888&source=wechat",
    "title": "限时特惠，立减50元",
    "coverUrl": "https://cdn.example.com/miniapp-cover.jpg"
  }'

批量发送（群发场景）

在 微信机器人开发 场景中，常见需求是向多个好友批量发送小程序卡片（如节日活动推送、私域促销通知）。可以循环调用接口并加入适当的发送间隔，避免频率过高触发风控：

pythonimport time
import requests

API_URL = "https://api.wechatapi.net/v1/message/miniapp-card"
TOKEN = "your_videos_api_token_here"
APP_ID = "your_device_app_id_here"

# 目标用户列表（从 CRM 或数据库中获取）
target_wxids = [
    "wxid_aaaaaa",
    "wxid_bbbbbb",
    "wxid_cccccc",
]

miniapp_info = {
    "miniAppId": "wx1234567890abcdef",
    "miniAppUsername": "gh_abcdef123456",
    "pagePath": "/pages/event/summer?utm_source=private",
    "title": "夏日大促，点击领取专属优惠券",
    "coverUrl": "https://cdn.example.com/summer-cover.jpg"
}

headers = {
    "VideosApi-token": TOKEN,
    "Content-Type": "application/json"
}

success_count = 0
fail_list = []

for wxid in target_wxids:
    payload = {"appId": APP_ID, "toWxid": wxid, **miniapp_info}
    resp = requests.post(API_URL, json=payload, headers=headers).json()

    if resp.get("ret") == 200:
        success_count += 1
        print(f"[OK] {wxid} -> msgId={resp['data']['msgId']}")
    else:
        fail_list.append({"wxid": wxid, "reason": resp.get("msg")})
        print(f"[FAIL] {wxid} -> {resp.get('msg')}")

    # 每条消息之间随机间隔 1~3 秒，降低风控概率
    time.sleep(1.5)

print(f"\n完成：成功 {success_count}/{len(target_wxids)} 条，失败 {len(fail_list)} 条")

实战注意事项

1. 小程序必须已上线且可访问

发送的小程序必须处于「已发布」状态，且其 AppID 对应的小程序确实存在。如果小程序已下架或 AppID 填写错误，消息虽然可能显示发送成功，但接收方点击卡片会出现「小程序已停服」或「未找到该小程序」的提示，严重影响用户体验和转化效果。建议在发送前先自测一次：手动在微信上转发该小程序页面，确认卡片可正常打开。

2. 封面图的选择直接影响点击率

小程序卡片的封面图是用户视觉焦点，建议遵循以下规范：

• 尺寸比例 5:4（如 500×400 像素），过高或过宽会被裁剪
• 文件格式 JPEG 或 PNG，大小不超过 300KB
• 图片背景避免纯黑或纯白，色彩对比度高的设计点击率更好
• 封面图应与页面内容强相关，避免误导用户

3. 发送频率与风控

个人微信账号在自动化发送消息时存在频率限制，尤其是短时间内向大量好友发送相同内容，可能触发微信的防刷机制，轻则消息静默，重则账号被限制发消息或封禁。建议：

• 每条消息之间保持 1~3 秒随机间隔
• 同一个账号单日发送量控制在合理范围内（具体阈值参考 WechatApi 官方文档说明）
• 发送内容保持适当多样性，避免大批量完全相同的消息

4. pagePath 参数的 UTM 追踪

在页面路径中附加 utm_source、utm_campaign 等追踪参数是量化私域营销效果的有效手段。小程序侧需要在 onLoad 生命周期中解析 options 参数并上报到埋点系统，这样就能在数据平台中区分来自不同渠道、不同批次推送的转化效果，为后续精细化运营提供数据支撑。

5. 结合 SCRM 场景使用

在 微信SCRM 系统中，小程序卡片消息通常结合用户标签、购买记录、互动历史等数据进行精准推送。例如：对「加购未付款」用户推送商品详情小程序页面，对「30天未复购」老客推送专属优惠券领取页。这种基于用户画像的定向推送，远比无差别群发更能提升转化率，也能减少打扰普通用户带来的好友流失。

消息发送后的状态追踪

发送接口返回的 msgId 可以用于后续的消息状态查询。WechatApi 提供消息回执回调（Webhook）机制：在控制台配置回调 URL 后，当消息触达、被阅读或发生错误时，服务端会主动推送事件通知到你的业务服务器，无需轮询查询，适合需要实时感知消息状态的场景（如客服系统、营销自动化平台）。

结合消息追踪与小程序内的埋点，可以建立完整的「推送 → 触达 → 点击 → 转化」漏斗分析，持续优化推送策略。

如需深入了解 微信API对接 的更多能力（如消息撤回、已读回执、文件发送等），可查阅 WechatApi 开发文档 获取完整接口列表和参数说明。

小结

微信小程序卡片消息因其零跳转摩擦的特性，是私域流量场景下转化效果最好的消息类型之一。通过个人微信账号发送小程序卡片，需要在协议层正确构造 XML 消息体并完成签名——这部分复杂度通过 WechatApi 的 HTTP 接口封装得到了彻底屏蔽，开发者只需关注业务参数（toWxid、miniAppId、pagePath、title、coverUrl）即可完成调用。实际落地时，注意控制发送频率、做好封面图设计、利用 pagePath 参数做好 UTM 追踪，并结合 SCRM 用户画像实现精准推送，才能将接口能力真正转化为业务价值。