微信发送名片消息接口

前言

在企业获客和私域运营场景中，批量推送好友名片是常见的裂变手段——客服向客户推荐同事、销售机器人在群内互推专属顾问、SCRM系统自动化导流都依赖这一能力。然而，微信官方开放平台并不向个人号开放名片消息接口，开发者若想以编程方式发送名片，必须借助基于底层协议实现的第三方 API。本文以 WechatApi 为例，完整拆解微信发送名片消息接口的实现原理、请求规范、参数说明与实战代码，帮助开发者快速落地。

名片消息的协议原理

微信的名片消息（Personal Card）在协议层是一种独立的消息类型，区别于文本、图片、链接等类型。它携带的核心字段是目标用户的 wxid（微信原始 ID）以及该用户的昵称、头像摘要等元信息，接收方点击后可直接添加好友。

从 iPad 协议维度看，微信客户端通过长连接将消息序列化后上行至微信服务器，服务器再下发至目标设备。微信 iPad 协议 是目前业内稳定性最高、与官方客户端行为最接近的私有协议实现路径，能够完整还原名片消息的构造格式，并保持与微信服务器的正常通信。相比 Hook 方案依赖本地 PC 客户端进程、Android 协议受制于多设备管控，iPad 协议在云端部署场景下具有更好的可用性。

WechatApi 平台正是建立在 iPad 协议之上，提供了统一的 HTTP REST 接口层，让开发者无需关心底层协议序列化细节，直接通过标准 HTTP POST 请求即可完成名片消息的发送。

接口调用规范

鉴权机制

WechatApi 采用请求头鉴权，每次 API 调用都需要在 HTTP Header 中携带两个关键字段：

appId 是设备维度的唯一标识，并非微信 AppID（公众号概念）。登录控制台 newmanager.wechatapi.net/dashboard/ 后，在「设备管理」页面可以看到每个在线微信号对应的 appId 值。

请求结构

发送名片消息的接口为 HTTP POST，请求体为 JSON 格式，核心参数包括：

• appId：发送方设备 ID
• toWxid：接收方的微信原始 ID（wxid\_xxxxxxxx 格式）或群 ID（xxxxxxxx@chatroom 格式）
• cardWxid：被推送名片的目标用户微信原始 ID

json{
  "appId": "YOUR_DEVICE_APP_ID",
  "toWxid": "wxid_receiver123456",
  "cardWxid": "wxid_targetcard789"
}

返回体统一格式如下：

json{
  "ret": 200,
  "msg": "发送成功",
  "data": {
    "msgId": "8765432109876543",
    "createTime": 1718251234
  }
}

ret 为 200 表示成功，其他状态码含义参见官方开发文档 post.wechatapi.net。

完整代码示例

Python 示例

下面是一个可直接参考的 Python 调用示例，使用 requests 库：

pythonimport requests

API_BASE = "https://api.wechatapi.net"   # 示意域名，实际以文档为准
TOKEN = "your_videos_api_token_here"
APP_ID = "your_device_app_id_here"

def send_card_message(to_wxid: str, card_wxid: str) -> dict:
    """
    发送名片消息
    :param to_wxid:   接收方 wxid 或群 chatroom ID
    :param card_wxid: 被推送名片的微信 ID
    :return: 接口返回 dict
    """
    url = f"{API_BASE}/v1/message/sendCard"
    headers = {
        "VideosApi-token": TOKEN,
        "Content-Type": "application/json",
    }
    payload = {
        "appId": APP_ID,
        "toWxid": to_wxid,
        "cardWxid": card_wxid,
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=10)
    resp.raise_for_status()
    result = resp.json()
    if result.get("ret") == 200:
        print(f"[OK] 名片已发送，msgId={result['data']['msgId']}")
    else:
        print(f"[ERROR] 发送失败：{result.get('msg')}")
    return result


if __name__ == "__main__":
    # 示例：向 wxid_demo001 发送 wxid_agent888 的名片
    send_card_message("wxid_demo001", "wxid_agent888")

Bash / cURL 示例

对于运维或快速验证场景，也可以直接用 cURL 测试：

bashcurl -X POST "https://api.wechatapi.net/v1/message/sendCard" \
  -H "VideosApi-token: your_videos_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your_device_app_id_here",
    "toWxid": "wxid_receiver123456",
    "cardWxid": "wxid_targetcard789"
  }'

成功返回示例：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "msgId": "7654321098765432",
    "createTime": 1718251800
  }
}

参数详解与常见错误码

主要请求参数

常见错误码

需要注意，cardWxid 所指定的用户必须是发送方微信号的好友或群成员，否则名片内容无法正常构造，接口会返回用户不存在的错误。

实战场景与使用技巧

场景一：SCRM 系统自动导流

在 微信 SCRM 场景中，当某个客服离职或岗位调整时，系统需要批量将其名下客户导流至新的负责人。此时可以通过遍历客户列表，循环调用名片接口，将新负责人的名片推送给每一位客户，引导客户主动添加。

实现要点：

1. 发送名片前先调用获取好友列表接口，确认新负责人 wxid 存在于当前设备的好友中；
2. 设置发送间隔（建议每条消息间隔 1-3 秒），避免触发微信频率风控；
3. 记录每次发送的 msgId 和 createTime，便于后续追踪和回溯。

场景二：群内互推专属顾问

在社群运营中，用户进群后机器人自动发送专属顾问的名片，是私域承接的常见玩法。结合 微信群管理机器人 的群事件监听能力，可以监听「新成员入群」事件，触发后自动向 toWxid 填入群 ID（xxxxx@chatroom）、cardWxid 填入顾问微信 ID 发送名片。这样群内所有成员都能看到这条名片消息，点击即可添加。

场景三：机器人自动化获客

在 微信机器人开发 场景中，可以设计关键词触发逻辑：当用户私信发送「加顾问」时，机器人自动回复一条名片消息，将业务顾问的微信推给对方，实现全流程无人值守。

发送频率与风控注意事项

使用名片消息接口需要注意以下几点，避免账号被微信风控：

1. 不要集中批量发送：短时间内向大量用户发送名片容易触发异常行为检测。建议使用队列异步发送，每条间隔 2-5 秒，每小时发送量控制在合理范围内。
2. 保持账号活跃：长期仅通过 API 发消息、不做其他正常社交行为的账号风险较高。建议让设备也保持正常的阅读朋友圈、主动发消息等操作。
3. 名片目标用户需是好友：如前所述，cardWxid 须是发送方的好友，否则名片无法正常被解析展示。在发送前可通过查询好友关系接口做前置校验。
4. 监控账号状态：通过 WechatApi 的设备状态接口定期检测在线状态，若检测到离线立即告警，防止发送失败堆积。

与其他消息类型的对比

名片消息在微信消息体系中具有较强的引导转化属性，与其他消息类型相比，各有适用场景：

从转化路径看，名片消息的路径最短——接收方点击「添加」即可直接发起好友申请，不需要手动搜索微信号，在私域引流中效率最高。

开发环境准备与快速上手

如果你刚接触 个人微信API 开发，以下是最快的上手路径：

1. 注册 WechatApi 账号：访问 newmanager.wechatapi.net/dashboard/ 完成注册；
2. 添加设备：扫码登录你的个人微信号，获取对应的 appId；
3. 生成 Token：在控制台「API 管理」页面创建访问令牌，复制 VideosApi-token；
4. 查阅文档：完整接口文档见 post.wechatapi.net，包含所有消息类型的详细参数说明；
5. 发起第一次调用：使用上文 cURL 示例，替换真实 token 和 appId 即可测试。

整个准备过程通常在 15 分钟内可以完成，平台提供免费试用额度，方便开发者在正式接入前进行充分验证。

小结

微信发送名片消息接口是私域运营和 SCRM 系统中高价值、但官方不开放的能力之一。本文系统介绍了其底层协议原理（iPad 协议实现）、统一的 HTTP POST + JSON 调用规范、鉴权方式（VideosApi-token + appId）、完整的 Python 和 cURL 代码示例，以及在 SCRM 导流、群机器人、自动化获客三大场景下的实战用法。使用时需重点关注发送频率管控和账号健康维护，在合规使用的前提下，名片消息能显著提升私域好友转化效率。如需快速落地，可直接接入 WechatApi 平台，开箱即用，无需自行处理复杂的协议层细节。