微信发送名片、小程序、链接卡片消息实战

前言

在做微信相关的自动化或机器人功能时，单纯的文字消息往往满足不了业务需求。真实场景里，我们常常需要把联系人名片推送给用户、把带封面图的链接卡片发到群里、或者拉起一个小程序落地页。这三类消息在视觉展示和点击转化上都比纯文字强得多，但它们的数据结构和发送逻辑也比普通文本复杂。

本文结合 HTTP 接口方式，系统梳理名片消息、小程序消息、链接（URL卡片）消息的报文格式、核心字段含义、调用示例，以及常见的坑和排查思路。所有代码均使用占位符，具体接口路径和字段名以官方文档为准。

一、三类富媒体消息概览

在深入每种消息的接口细节之前，先做一个横向比较，理清它们的适用场景和核心差异。

三者都属于结构化消息（非纯文字），需要调用专属接口，且字段数量明显多于 postText。

二、名片消息：分享联系人

2.1 使用场景

名片消息最常见于两类场景：

1. 把客服微信名片发给有咨询意向的用户；
2. 在用户裂变场景里，把指定账号推荐给新用户，引导主动添加。

名片本质上是把一个微信用户的基本资料"打包投递"给接收方。接收方点击后可以直接查看主页并发起好友申请。

2.2 接口调用

接口路径示例：/message/postNameCard（以官方文档为准）

pythonimport requests

BASE    = "https://你的接口域名"   # 注册后在官方文档获取
TOKEN   = "你的Token"
APPID   = "你的appId"
HEADERS = {"token": TOKEN}        # 鉴权字段名以官方文档为准

def send_name_card(to_wxid: str, card_wxid: str):
    """
    发送名片消息
    :param to_wxid:   接收方 wxid（个人或群）
    :param card_wxid: 被分享的联系人 wxid
    """
    payload = {
        "appId":    APPID,
        "toWxid":   to_wxid,
        "cardWxid": card_wxid,   # 字段名以官方文档为准
    }
    resp = requests.post(f"{BASE}/message/postNameCard", json=payload, headers=HEADERS)
    data = resp.json()
    if data.get("ret") == 200:
        print("名片发送成功")
    else:
        print("发送失败：", data.get("msg"))

# 示例调用
send_name_card(to_wxid="目标wxid", card_wxid="被推荐人wxid")

2.3 关键注意点

• card_wxid 必须是真实存在于通讯录或至少在平台侧可查到基础信息的 wxid，否则接口会返回错误或接收方看到"账号异常"；
• 发名片给群时，toWxid 填群 ID（通常以 @chatroom 结尾），效果与个人会话一致；
• 名片消息不支持"撤回后重发"的自动重试，建议在回调确认接收后再做下一步动作；
• 批量推送名片时注意频率，每批次之间随机间隔 5–15 秒，避免触发限制。

三、小程序消息：拉起落地页

3.1 小程序消息的构成

一条完整的小程序消息包含以下要素：

其中 miniAppId 和 userName 是微信给每个小程序分配的标识，可以在微信公众平台的小程序后台查到。miniPath 决定了用户点击后进入哪个页面，支持带参数的完整路径。

3.2 接口调用

接口路径示例：/message/postMiniApp（以官方文档为准）

pythonimport requests

BASE    = "https://你的接口域名"
TOKEN   = "你的Token"
APPID   = "你的appId"
HEADERS = {"token": TOKEN}

def send_mini_app(to_wxid: str, mini_app_id: str, path: str,
                  title: str, thumb_url: str, user_name: str):
    """
    发送小程序消息
    :param to_wxid:     接收方 wxid 或群 ID
    :param mini_app_id: 小程序 AppID
    :param path:        跳转页面路径（含参数）
    :param title:       消息卡片标题
    :param thumb_url:   封面图 URL（HTTPS）
    :param user_name:   小程序原始 ID（gh_xxx）
    """
    payload = {
        "appId":      APPID,
        "toWxid":     to_wxid,
        "miniAppId":  mini_app_id,   # 以官方文档字段为准
        "miniPath":   path,
        "thumbUrl":   thumb_url,
        "title":      title,
        "userName":   user_name,
    }
    resp = requests.post(f"{BASE}/message/postMiniApp", json=payload, headers=HEADERS)
    data = resp.json()
    if data.get("ret") == 200:
        print("小程序消息发送成功")
    else:
        print("发送失败：", data.get("msg"))

# 示例调用
send_mini_app(
    to_wxid    = "目标wxid",
    mini_app_id= "wx1234567890abcdef",
    path       = "pages/index/index?source=bot",
    title      = "限时活动，点击参与",
    thumb_url  = "https://example.com/cover.jpg",
    user_name  = "gh_xxxxxxxxxxxxxxxx",
)

3.3 封面图的处理建议

封面图对点击率影响显著，有以下几点实践建议：

1. 尺寸：微信对封面图有压缩，建议原图 5:4 比例，宽度 520px 以上；
2. 格式：优先 JPEG，PNG 也可以，GIF 动图会被静帧处理；
3. 地址稳定性：thumbUrl 要保证长期可访问，不要用本地临时地址；
4. 内容合规：封面图中不能出现二维码、价格数字（微信侧过滤）。

3.4 小程序路径参数的实际用途

miniPath 里的 Query 参数是追踪来源的好手段。例如：

pages/activity/index?channel=wechat_bot&uid=10086

小程序前端拿到 options.channel 和 options.uid 后，就能区分哪条机器人消息带来了用户、绑定哪个账号。这是免改接口做渠道统计的常见方案，不需要额外开发转链服务。

四、链接卡片消息：URL 富媒体推送

4.1 链接卡片 vs 直接发 URL

直接把 URL 发成文字，接收方看到的是一串蓝色链接，点击后跳出微信打开浏览器。而链接卡片消息（postLink）会渲染成带缩略图、标题和摘要的卡片，视觉上更接近公众号文章分享，点击率通常高得多。

4.2 接口调用

接口路径示例：/message/postLink（以官方文档为准）

pythonimport requests

BASE    = "https://你的接口域名"
TOKEN   = "你的Token"
APPID   = "你的appId"
HEADERS = {"token": TOKEN}

def send_link_card(to_wxid: str, title: str, desc: str,
                   url: str, thumb_url: str):
    """
    发送链接卡片消息
    :param to_wxid:   接收方 wxid 或群 ID
    :param title:     卡片标题（建议 ≤30 字）
    :param desc:      摘要（建议 ≤60 字）
    :param url:       点击后跳转的目标 URL
    :param thumb_url: 缩略图 URL（HTTPS）
    """
    payload = {
        "appId":    APPID,
        "toWxid":   to_wxid,
        "title":    title,
        "desc":     desc,
        "url":      url,
        "thumbUrl": thumb_url,   # 字段名以官方文档为准
    }
    resp = requests.post(f"{BASE}/message/postLink", json=payload, headers=HEADERS)
    data = resp.json()
    if data.get("ret") == 200:
        print("链接卡片发送成功")
    else:
        print("发送失败：", data.get("msg"))

# 示例调用
send_link_card(
    to_wxid   = "目标wxid",
    title     = "2025 年 Python 异步编程实战",
    desc      = "从 asyncio 基础到生产级并发模式，图文并茂",
    url       = "https://your-site.com/article/python-async",
    thumb_url = "https://your-site.com/images/python-async-cover.jpg",
)

4.3 字段填写的常见误区

标题长度：超过约 30 个字符，微信客户端会截断显示，建议控制在 20–28 字之间，把最重要的信息放在前面。

摘要（desc）：这是卡片正文区域显示的一小段描述，不是 HTML meta description，纯文本即可，不支持换行符。

缩略图：与小程序封面图类似，要求 HTTPS、稳定可访问。如果 thumbUrl 返回 4xx/5xx，微信会显示默认灰图，严重影响视觉效果。

目标 URL：必须是完整的、以 http:// 或 https:// 开头的合法 URL。如果你的 H5 页面带了登录 Token 或用户 ID 在 URL 参数里，注意做好鉴权，防止参数泄漏。

4.4 批量发链接卡片的频率控制

群发或多用户推送链接卡片时，频率过高容易被风控。以下是实践中较为安全的策略：

pythonimport time
import random

def batch_send_link(wxid_list: list, title: str, desc: str, url: str, thumb_url: str):
    """批量发送链接卡片，含随机间隔"""
    for wxid in wxid_list:
        send_link_card(wxid, title, desc, url, thumb_url)
        # 随机间隔 3–8 秒，降低风控概率
        time.sleep(random.uniform(3, 8))

如果是群发，还建议把任务分批次，每批次 20–30 条，批次之间间隔 2–5 分钟。

五、托管 HTTP 接口与自建方案的对比

实现上述三类消息，大体有两条路：一是自行维护微信客户端（如 PC 微信注入、安卓模拟器）暴露 HTTP 接口；二是使用现成的托管服务。

自建方案的主要挑战在于：微信客户端版本更新频繁，协议逆向维护成本高；多账号时还需要解决多实例隔离和状态同步。WechatApi 提供扫码登录、消息收发、好友与群管理等 REST 接口，HTTP 调用即可，官网 wechatapi.net 有详细的接口文档和在线调试工具，适合快速验证上面三类消息的格式是否正确。

对于已有自建环境的团队，本文的接口结构和字段说明同样适用，按各自环境的实际 endpoint 替换即可。

六、常见问题排查

6.1 名片消息接收方显示"名片异常"

• 检查 card_wxid 是否是有效的微信 ID，而非备注名或手机号；
• 部分情况下，被分享人的隐私设置会阻止名片展示，属于微信侧限制，接口本身无法绕过。

6.2 小程序消息发出后显示"无法打开小程序"

排查顺序：

1. 确认 miniAppId 和 userName 是否对应同一个小程序；
2. 确认小程序状态为"已发布"（未上线的小程序只有体验者能打开）；
3. 确认 miniPath 对应的页面在 app.json 的 pages 中已注册；
4. 部分小程序强制要求登录态，path 里少了必要参数会跳转失败，请联系小程序开发者确认路径。

6.3 链接卡片缩略图不显示

• 图片 URL 必须 HTTPS，HTTP 链接会被微信拦截；
• 检查图片服务器的 CORS 和防盗链配置，确保微信爬虫可以访问；
• 图片体积建议不超过 500 KB，过大会超时导致加载失败；
• 如果用 CDN，确认 CDN 没有对 User-Agent 做过滤。

6.4 接口返回成功但消息未到达

这是接口调用和消息实际投递分离导致的。接口返回 ret==200 只代表平台侧接收了请求，真正的投递状态需要通过回调确认。建议用 setCallback 设置回调地址，监听回调中的 msgId 来核实是否成功投递。另外要确保发消息的账号处于在线状态，离线账号的消息会被丢弃而非排队。

七、三类消息的选型建议

根据业务目标选择合适的消息类型，能显著提升转化效果：

在消息类型之外，发送时机和发送频率往往对结果影响更大。一条在用户主动咨询后 10 秒内发出的名片消息，效果远好于定时批量推送。

总结

名片消息、小程序消息、链接卡片消息是微信自动化场景里使用频率最高的三类富媒体消息。它们的核心差异在于数据结构：名片靠 wxid、小程序靠 AppID 和页面路径、链接卡片靠 URL 和图文元数据。掌握各自的字段含义和调用细节，再结合合理的频率控制，就能稳定地把这三类消息集成进业务流程。

代码示例中所有接口地址、字段名均为示例占位，实际开发请以所使用平台的官方文档为准。