微信发送链接卡片消息接口

前言

在企业私域运营和客户触达场景中，链接卡片消息是微信里点击率最高的消息类型之一：它带有标题、摘要、缩略图，视觉上远比纯文本链接更吸引眼球。然而个人微信并没有官方开放API，开发者想通过程序自动发送链接卡片，必须依赖第三方接入方案。本文系统讲解链接卡片消息的数据结构、接口调用流程、常见坑点与最佳实践，帮助你快速落地自动化消息投递。

链接卡片消息与普通链接的本质区别

很多开发者第一次接触这个需求时，会有一个误区：直接在消息体里发一段 URL，用户点击不就行了？

实际上，微信对消息类型做了严格区分。普通文本消息里的链接只是一段可点击的蓝色字符串，没有标题、没有摘要、没有缩略图预览。而链接卡片消息（在微信协议层通常被称为 App 消息或 Appmsg 消息）本质上是一段结构化的 XML 数据，经微信客户端解析后渲染成带封面图的卡片样式，点击后在微信内置浏览器打开目标 URL。

两者的核心差异如下表所示：

链接卡片的 XML 核心字段包括：title（标题）、des（摘要/描述）、url（跳转地址）、thumburl（缩略图地址）以及 appid（来源应用标识，可留空或填写通用值）。理解这一结构对后面调用接口拼装参数至关重要。

为什么个人微信发链接卡片需要特殊方案

微信的企业号（企业微信）有官方开放平台，但覆盖的是员工内部沟通场景，无法直接触达个人微信用户的私信或个人微信群。个人微信的消息收发能力，微信官方始终没有开放标准 API。

目前业界主流的技术方案是基于 iPad 协议进行接入。这类方案通过模拟 iPad 客户端与微信服务器的通信协议，在服务器侧维持一个登录态（设备实例），进而实现消息收发、好友管理、群操作等能力。

WechatApi 正是一个基于 iPad 协议构建的个人微信 HTTP API 服务。它将复杂的协议层细节封装为标准的 RESTful 接口，开发者只需发起普通 HTTP 请求即可完成消息发送，无需了解微信底层协议的任何细节。相比自行研究协议、自行维护长连接会话，接入现成的稳定服务能节省大量开发和运维成本。

关于 iPad 协议的技术背景，可参考 微信iPad协议详解，其中对协议稳定性、设备隔离等问题有更深入的说明。

接口调用前的准备工作

在正式编写代码之前，需要完成以下几项准备：

1. 注册并获取 API 凭证

访问 WechatApi 控制台 完成注册，在个人中心可以看到你的 VideosApi-token。这是所有接口调用的鉴权凭证，需要放在每个请求的 HTTP Header 中。

2. 创建设备实例，获取 appId

每个登录的微信账号对应一个设备实例，创建后系统会分配一个唯一的 appId（即设备 ID）。后续所有业务请求都需要携带 appId 来指定操作哪一个登录中的微信账号。一个 token 下可以管理多个 appId，适合需要多号并发的业务场景。

3. 完成微信账号扫码登录

通过 API 拉起登录二维码，使用对应微信账号扫码，设备实例进入在线状态后即可发送消息。

4. 确认目标缩略图可公网访问

链接卡片的缩略图 thumburl 必须是一个可以被微信服务器拉取的公网图片地址（HTTPS 优先），否则卡片中封面图会显示为空白或默认图标，严重影响点击率。

发送链接卡片消息的接口参数详解

WechatApi 发送链接卡片消息使用 HTTP POST 方式，请求体为 JSON 格式，鉴权通过 Header 中的 VideosApi-token 字段传递。

核心请求参数如下：

返回体统一格式为：

json{
  "ret": 200,
  "msg": "发送成功",
  "data": {
    "msgId": "1234567890_987654321",
    "createTime": 1718000000
  }
}

其中 ret 为 200 表示成功，非 200 时 msg 字段会包含具体错误描述，例如 "账号未登录" 或 "接收方wxid不存在" 等，便于排查问题。

Python 调用示例

下面是一个完整的 Python 调用示例，展示如何向指定微信好友发送链接卡片消息：

pythonimport requests
import json

# 鉴权 token，从控制台获取
API_TOKEN = "your_videos_api_token_here"

# 接口基础地址（示意，请以文档为准）
BASE_URL = "https://api.wechatapi.net/v1"

def send_link_card(app_id: str, to_wxid: str, title: str, desc: str,
                   link_url: str, thumb_url: str, app_name: str = "WechatApi") -> dict:
    """
    发送链接卡片消息
    :param app_id:    设备ID（微信账号实例）
    :param to_wxid:   接收方wxid或群ID
    :param title:     卡片标题
    :param desc:      卡片摘要
    :param link_url:  跳转URL
    :param thumb_url: 缩略图URL（公网可访问）
    :param app_name:  来源应用名称
    """
    url = f"{BASE_URL}/message/send-link"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": API_TOKEN
    }
    payload = {
        "appId": app_id,
        "toWxid": to_wxid,
        "title": title,
        "desc": desc,
        "linkUrl": link_url,
        "thumbUrl": thumb_url,
        "appName": app_name
    }
    resp = requests.post(url, headers=headers, json=payload, timeout=10)
    result = resp.json()
    if result.get("ret") != 200:
        raise RuntimeError(f"发送失败: {result.get('msg')}")
    return result["data"]

if __name__ == "__main__":
    data = send_link_card(
        app_id="your_device_app_id",
        to_wxid="wxid_xxxxxxxxxxxxxx",
        title="2024年私域流量运营白皮书",
        desc="私域运营最全指南，涵盖引流、转化、复购三大核心环节",
        link_url="https://example.com/whitepaper?utm_source=wechat&utm_medium=card",
        thumb_url="https://example.com/images/whitepaper-cover.jpg"
    )
    print(f"消息发送成功，msgId: {data['msgId']}")

上面的代码中有几个值得注意的细节：

• link_url 中附加了 UTM 参数，便于在 Google Analytics 或其他统计平台追踪来自微信的流量来源。
• timeout=10 避免网络抖动时程序无限等待，生产环境建议结合重试机制使用。
• 错误处理直接抛出异常，调用方可以根据业务需要决定是重试还是记录日志。

批量发送与群发场景的 Shell 示例

在实际运营中，往往需要给一批用户批量发送链接卡片。下面的 bash 脚本展示了如何基于用户列表批量调用接口，并加入简单的限速控制，避免触发微信风控：

bash#!/bin/bash

# 配置区
API_TOKEN="your_videos_api_token_here"
APP_ID="your_device_app_id"
BASE_URL="https://api.wechatapi.net/v1/message/send-link"
TITLE="独家活动邀请：限时免费领取资料包"
DESC="点击领取，仅限今日有效"
LINK_URL="https://example.com/activity/free-resource"
THUMB_URL="https://example.com/images/activity-banner.jpg"

# 用户列表文件，每行一个 wxid
WXID_LIST="wxid_list.txt"

# 发送间隔（秒），建议3-8秒随机化，避免风控
MIN_SLEEP=3
MAX_SLEEP=8

while IFS= read -r wxid; do
    [ -z "$wxid" ] && continue  # 跳过空行

    PAYLOAD=$(cat <<EOF
{
  "appId": "$APP_ID",
  "toWxid": "$wxid",
  "title": "$TITLE",
  "desc": "$DESC",
  "linkUrl": "$LINK_URL",
  "thumbUrl": "$THUMB_URL"
}
EOF
)
    RESPONSE=$(curl -s -X POST "$BASE_URL" \
        -H "Content-Type: application/json" \
        -H "VideosApi-token: $API_TOKEN" \
        -d "$PAYLOAD")

    RET=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('ret',''))")

    if [ "$RET" = "200" ]; then
        echo "[OK] 已发送至: $wxid"
    else
        MSG=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('msg','unknown'))")
        echo "[FAIL] $wxid 发送失败: $MSG"
    fi

    # 随机等待，模拟人工操作节奏
    SLEEP_TIME=$(( RANDOM % (MAX_SLEEP - MIN_SLEEP + 1) + MIN_SLEEP ))
    sleep "$SLEEP_TIME"

done < "$WXID_LIST"

echo "批量发送完成"

这段脚本的限速逻辑（随机 3-8 秒间隔）在实际私域运营中非常重要。微信的风控系统会识别异常的消息发送频率，过于密集的批量操作可能导致账号被限制发送消息甚至封号。合理的发送节奏是保障账号健康的基本前提。

链接卡片消息的实际应用场景

链接卡片消息在私域运营中的用途非常广泛，以下是几个高价值场景：

电商促销推送：将活动落地页包装成链接卡片，卡片封面用高质量活动海报，标题突出折扣力度，摘要说明有效期。相比纯文本，卡片式消息能显著提升用户的点击意愿。

内容营销分发：将公众号文章、行业报告、白皮书的链接以卡片形式推送给目标用户群，配合针对性的摘要文案，精准触达有阅读意向的用户。

客服场景的导航卡片：客服机器人在解答用户问题时，附带发送相关帮助文档或产品介绍的链接卡片，用户在对话界面即可直接跳转，降低操作门槛。关于客服机器人的完整实现方案，可参考 微信客服机器人开发指南。

社群活动通知：在微信群中发送活动报名页面的链接卡片，比@所有人加文字+链接的组合更直观，群成员点击率更高。

CRM 系统集成：将链接卡片发送能力集成到企业 CRM 或 SCRM 系统中，实现用户分层触达、消息效果追踪。WechatApi 的接口可以方便地与主流 CRM 系统对接，详见 微信SCRM方案。

常见问题与避坑指南

问题1：卡片封面图不显示

原因通常是 thumbUrl 指向的图片不可被公网访问，或图片 URL 包含中文、特殊字符导致请求失败。解决方法：确保图片托管在有公网 IP 的服务器或 CDN 上，URL 做好编码，并在发送前用浏览器验证能否直接访问。

问题2：卡片在对方手机上显示为灰色或"该内容暂不可访问"

这通常是因为目标 URL 被微信内置安全系统屏蔽，或域名尚未经过微信安全认证。建议使用域名白名单较好的正规域名，避免使用短链服务（部分短链服务商域名已被批量屏蔽）。

问题3：发送成功但接收方看不到消息

需检查两点：一是接收方是否已将你的账号拉黑或设置了消息过滤；二是当日发送消息数量是否超过账号限额。通过 WechatApi 的接口可以查询当前账号的消息发送状态和配额信息。

问题4：title 或 desc 超长导致截断

微信客户端对卡片标题和摘要的显示字数有限制，超出部分会以省略号截断。建议标题控制在 20 个中文字以内，摘要控制在 45 个中文字以内，确保核心信息在截断前完整展示。

问题5：多账号并发发送时消息错发

每个请求中必须明确指定 appId，多账号管理时建议在业务层维护一张 appId 与业务账号的映射表，避免混用。WechatApi 支持在同一个 token 下管理多个设备实例，适合多号并发的私域运营场景。

问题6：接口返回 401 或鉴权失败

检查 Header 中 VideosApi-token 的值是否正确，注意不要多加空格或换行符。token 有效期请参考控制台说明，过期后需重新获取。

安全与合规注意事项

使用个人微信接口进行商业运营时，合规问题不可忽视：

• 用户授权：向用户发送营销消息前，务必确认已获得用户明确授权，遵守《个人信息保护法》的相关规定。
• 发送频率：避免高频骚扰同一用户，对于营销类消息建议每日每用户不超过1-2条。
• 内容合规：卡片内容不得包含违法违规信息，链接目标页面的内容同样需要合规审查。
• 账号健康：建议对发送行为做日志记录，一旦发现账号异常（如消息发送量突降、登录状态频繁掉线），及时排查原因并调整发送策略。

WechatApi 的 微信二次开发 文档中对合规使用有详细的说明和建议，在正式上线前建议仔细阅读。

小结

微信链接卡片消息凭借其视觉优势和良好的点击转化，是私域运营中不可缺少的消息类型。本文系统梳理了链接卡片的数据结构、接口参数、Python 和 Shell 调用示例、多场景应用以及常见坑点，覆盖了从开发到生产上线的完整链路。

对于需要在个人微信上实现程序化消息发送的开发者而言，选择一个稳定、文档完善的 API 服务是降低开发成本的关键。WechatApi 基于 iPad 协议，提供链接卡片、图片、文件、小程序等多种消息类型的发送能力，控制台地址：https://newmanager.wechatapi.net/dashboard/，开发文档：https://post.wechatapi.net，欢迎注册试用。