企业微信模板卡片消息发送指南：3 种卡片类型与 10+ 参数详解

企业微信模板卡片消息发送指南：3 种卡片类型与 10+ 参数详解

在企业微信的生态中，消息交互是连接企业与员工、客户的重要纽带。传统的文本消息已经无法满足日益复杂的业务场景需求，而模板卡片消息以其丰富的视觉呈现和交互能力，成为提升用户体验的利器。本文将深入解析企业微信自建应用中三种核心模板卡片类型，并通过实际案例详解超过10个关键参数的配置方法与效果。

1. 模板卡片消息概述与基础配置

模板卡片消息是企业微信提供的一种结构化消息形式，相比普通文本消息，它能通过图文混排、按钮交互等元素，实现更直观的信息传达和更高效的业务处理。要使用模板卡片消息功能，首先需要完成基础配置：

1. 开通API接收消息功能
   在自建应用后台的"接收消息"设置中，开启API接收并配置以下参数：

   • URL：接收消息的服务器地址（需支持HTTPS）
   • Token：用于生成签名的自定义字符串
   • EncodingAESKey：43位的加密密钥（Base64编码）

2. 验证URL有效性
   企业微信会发送GET请求到配置的URL，服务端需实现签名验证和消息解密：

# Python示例：验证URL有效性 from werobot.contrib.work import WeRoBot robot = WeRoBot(token='YOUR_TOKEN', encoding_aes_key='YOUR_AES_KEY', corp_id='YOUR_CORP_ID') @robot.get def verify(msg_signature, timestamp, nonce, echostr): return robot.crypto.check_signature( msg_signature, timestamp, nonce, echostr)

3. 消息接收处理
   验证通过后，企业微信会推送事件和消息到该URL，需处理POST请求：

@robot.post def handle_messages(request): msg = robot.parse_message(request.data) # 处理消息逻辑 return "success" # 必须先返回success防止重试

关键点：回调配置是企业微信与自建应用双向通信的基础，必须确保服务端能正确处理验证请求和消息解密。如果消息处理耗时较长，应先返回success再异步处理业务逻辑，避免超时重试。

2. 文本通知型卡片（text_notice）深度解析

文本通知型卡片是最基础的模板卡片类型，适用于简单的通知场景，如系统提醒、流程通知等。其核心结构包括：

{ "msgtype": "template_card", "template_card": { "card_type": "text_notice", "main_title": { "title": "会议提醒", "desc": "您有一个即将开始的会议" }, "emphasis_content": { "title": "15:00", "desc": "今天" }, "sub_title_text": "主题：Q3产品规划讨论会", "horizontal_content_list": [ { "keyname": "地点", "value": "3楼会议室" }, { "type": 1, "keyname": "会议资料", "value": "点击查看", "url": "https://example.com/docs" } ], "card_action": { "type": 1, "url": "https://example.com/meeting/123" } } }

2.1 核心参数详解

2.2 高级功能实现

动态菜单交互：通过action_menu添加右上角菜单，用户选择后触发回调事件：

"action_menu": { "desc": "更多操作", "action_list": [ {"text": "接受邀请", "key": "accept"}, {"text": "拒绝邀请", "key": "reject"} ] }

消息去重控制：利用以下参数避免重复消息打扰：

• enable_duplicate_check: 1（开启）
• duplicate_check_interval: 1800（秒）

实际案例：审批通知卡片
将审批系统的通知转化为交互式卡片，包含审批类型、申请人等关键信息，并通过水平列表展示明细，点击可跳转到审批详情页。

3. 图文展示型卡片（news_notice）实战指南

图文展示型卡片适合需要丰富视觉呈现的场景，如新闻公告、产品推广等。其典型结构如下：

{ "card_type": "news_notice", "source": { "icon_url": "https://example.com/logo.png", "desc": "人力资源部", "desc_color": 1 }, "main_title": { "title": "2024年员工福利计划更新", "desc": "年度重要更新，请务必查阅" }, "image_text_area": { "type": 1, "url": "https://example.com/benefits", "title": "点击查看详情", "desc": "涵盖医疗保险、年假等多项更新", "image_url": "https://example.com/benefits.jpg" }, "vertical_content_list": [ { "title": "医疗险升级", "desc": "覆盖范围扩大至三甲医院特需部" } ], "jump_list": [ { "type": 1, "title": "政策全文", "url": "https://example.com/full-text" } ] }

3.1 视觉元素搭配技巧

1. 图片比例控制
   通过card_image.aspect_ratio设置宽高比（1.3-2.25），确保图片显示效果：

   "card_image": { "url": "https://example.com/benefits.jpg", "aspect_ratio": 1.78 // 16:9比例 }

2. 图文混排布局
   image_text_area实现左图右文效果，适合产品介绍：

   字段	说明	示例值
   type	交互类型（0/1/2）	1（跳转URL）
   title	标题（≤100字）	"新品发布会"
   desc	描述（≤150字）	"点击了解产品详情"

3. 内容结构化展示
   使用vertical_content_list垂直列表展示多个信息点（≤4项），每项包含：

   • title：信息点标题（≤38字）
   • desc：详细说明（≤150字）

3.2 交互增强方案

双跳转引导：结合jump_list（≤3项）和card_action提供多入口：

• 主图/文区域点击（card_action）
• 底部跳转链接（jump_list）

引用区域：通过quote_area突出重要内容：

"quote_area": { "type": 1, "url": "https://example.com/quote", "title": "核心政策变更", "quote_text": "年假天数根据工龄计算，最高可达15天" }

实际案例：产品发布公告
将产品特性通过图文混排展示，主图区域链接到产品页，底部跳转链接分别指向技术文档、购买页面和客服咨询。

4. 按钮交互型卡片开发进阶

按钮交互型卡片（button_interaction）支持用户直接在消息内完成操作，极大提升交互效率。其完整参数结构如下：

{ "card_type": "button_interaction", "main_title": { "title": "会议室预订确认", "desc": "请确认您的预订信息" }, "button_selection": { "question_key": "confirm", "title": "是否确认预订？", "option_list": [ {"id": "yes", "text": "确认"}, {"id": "no", "text": "取消"} ] }, "interaction_buttons": [ { "text": "修改时间", "style": 1, "key": "change_time" } ], "quote_area": { "type": 0, "title": "预订详情", "quote_text": "时间：今天15:00-16:00\n地点：3楼会议室A" } }

4.1 交互元素详解

1. 按钮选择（button_selection）
实现单选/多选问题，用户选择后触发回调：

2. 操作按钮（interaction_buttons）
底部操作区按钮（≤3个），支持不同样式：

{ "text": "紧急联系", // ≤12字 "style": 1, // 0-灰色 1-主色 "key": "urgent" // 回调标识 }

4.2 回调处理机制

当用户点击交互元素时，企业微信会推送事件到配置的回调URL：

<xml> <Event>template_card_event</Event> <EventKey>BUTTON_KEY</EventKey> <TaskId>TASK_ID</TaskId> <ResponseCode>RESP_CODE</ResponseCode> </xml>

关键处理逻辑：

1. 通过TaskId关联原始消息
2. 根据EventKey识别具体交互元素
3. 可选调用 更新模板卡片消息接口 动态更新卡片

Java示例：处理回调事件

@RequestMapping("/callback") public String handleCallback( @RequestParam String msg_signature, @RequestParam String timestamp, @RequestParam String nonce, @RequestBody String xmlData) { // 1. 解密消息 String plainText = decryptMsg(msg_signature, timestamp, nonce, xmlData); // 2. 解析事件类型 if (plainText.contains("template_card_event")) { String eventKey = extractXmlValue(plainText, "EventKey"); String taskId = extractXmlValue(plainText, "TaskId"); // 3. 业务处理 if ("confirm_yes".equals(eventKey)) { bookingService.confirmReservation(taskId); } } return "success"; }

4.3 性能优化建议

1. 任务ID（task_id）设计

   • 全局唯一且包含业务标识（如"reservation_123"）
   • 可解码出业务类型和ID，减少数据库查询

2. 异步处理模式
   对于耗时操作：

   • 立即返回"success"
   • 通过task_id查询原始消息
   • 异步完成后调用接口更新卡片状态

3. 状态跟踪
   使用以下字段记录交互状态：

   "replace_text": "已确认", // 替换按钮文本 "disabled": true // 禁用已操作按钮

5. 企业微信模板卡片消息的18个实战技巧

在实际开发中，我们总结了以下提升模板卡片效果的经验：

5.1 内容优化技巧

1. 关键数据突出
   使用emphasis_content强化核心数字：

   "emphasis_content": { "title": "¥1,299", "desc": "优惠价" }

2. 智能折叠长文本
   对sub_title_text等长字段：

   • 前150字确保包含核心信息
   • 用\n控制换行位置
   • 重要内容前置

3. 动态内容更新
   通过 更新模板卡片消息 接口实现：

   requests.post( "https://qyapi.weixin.qq.com/cgi-bin/message/update_template_card", params={"access_token": token}, json={ "userids": ["user1"], "task_id": "task_123", "template_card": updated_card } )

5.2 交互设计原则

1. 主次操作分离

   • 主要操作：放在card_action（整卡点击）
   • 次要操作：放在interaction_buttons（底部按钮）
   • 补充操作：action_menu（右上角菜单）

2. 视觉动线引导

   graph LR A[主标题] --> B[强调内容] B --> C[图文区域] C --> D[水平列表] D --> E[操作按钮]

3. 状态反馈机制

   • 操作后立即更新按钮状态（禁用/文本变更）
   • 重要操作添加二次确认
   • 错误情况显示replace_text提示

5.3 企业微信模板卡片消息的调试与排查

当模板卡片消息出现异常时，可按以下步骤排查：

1. 基础检查清单

• 确认access_token有效且未过期
• 检查消息体是否符合JSON格式
• 验证必填参数是否齐全

2. 特殊错误码处理

3. 调试工具推荐

1. 企业微信提供的 接口调试工具
2. Postman模拟消息发送
3. 本地搭建消息接收服务（如ngrok穿透）

# 使用ngrok建立临时测试环境 ngrok http 8080

在企业微信的实际项目中，模板卡片消息已经显著提升了消息触达率和操作转化率。某CRM系统接入后，客户跟进提醒的点击率从12%提升至63%，审批流程的平均处理时间缩短了40%。这些数据验证了模板卡片在提升企业沟通效率方面的巨大价值。