企业微信模板卡片配置:五种卡片必填字段与 12 个配错,发送前一次校验完(2026 版,附完整代码)
卡片 JSON 写完,接口调了,返回一个错误码。改一版,再调,换个错误码。
这种来回大部分时候不是因为不懂业务,而是因为模板卡片的必填规则是「按卡片类型分叉」的:同一个字段在 A 类型必填、在 B 类型选填、在 C 类型压根不存在。凭一份通用示例改,很容易改出个四不像。
这篇把五种卡片的必填与条件必填规则列全,给一个发送前就能跑完的校验器,把 12 个常见配错一次拦下。重点在「发出去之前」,不涉及点击回调怎么处理。
一、先分清:五种卡片,只有三种能交互
| card_type | 中文 | 能回调更新 | 版本要求 |
|---|---|---|---|
text_notice | 文本通知型 | 仅当填了 action_menu | 3.1.6+ |
news_notice | 图文展示型 | 仅当填了 action_menu | 3.1.6+ |
button_interaction | 按钮交互型 | 是 | 3.1.6+ |
vote_interaction | 投票选择型 | 是 | 3.1.12+ |
multiple_interaction | 多项选择型 | 是 | 3.1.12+ |
官方原文的表述是:仅有按钮交互型、投票选择型、多项选择型,以及填写了 action_menu 字段的文本通知型、图文展示型卡片,支持回调更新或通过接口更新卡片。
这条决定选型:想让用户点一下就把结果写回你的系统,前两种默认不行,得加 action_menu(右上角菜单)才行。很多人拿 text_notice 加了两个按钮就以为能交互——那是 button_interaction 才有的字段。
还有两条硬限制,写在文档里但极易漏看:
- 微工作台(原企业号)不支持展示模板卡片消息。
- 没有配置回调接口的应用不可发送支持回调的卡片。
第二条是「卡片发不出去」的头号原因,而且跟你 JSON 写得对不对完全无关。第五节专门验它。
二、前置条件:跟着做需要准备什么
- Python 3(跑校验器,只用标准库)
- 一个企业微信自建应用,拿到
agentid - 如果要发交互卡片:先在应用里配好接收消息的回调 URL 并通过验签
最后一条是前置条件,不是可选步骤。没配回调就发交互卡片,官方明确不允许。
本文校验器不发送任何真实消息,示例里的 agentid、userid、域名均为占位。
三、最容易踩的一条:task_id 按字节算,且字符集受限
官方对 task_id 的原文约束是:
任务id,同一个应用任务id不能重复,只能由**数字、字母和"_-@"**组成,最长128字节
三个约束叠在一起,而中文场景下三个都容易犯。跑一下:
== 0. 字节 vs 字符:中文 task_id 为什么必错 ==
官方 task_id 只允许 数字/字母/_-@,且最长 128 字节(按字节不是字符)
approval_20261119_001 字符数=21 字节数=21 字符集合法 长度OK
审批_20261119_001 字符数=15 字节数=19 字符集非法 长度OK
approval-20261119@001 字符数=21 字节数=21 字符集合法 长度OK
approval 20261119 字符数=17 字节数=17 字符集非法 长度OK
aaaaaaaaaaaaaaaaaaaaaaa... 字符数=128 字节数=128 字符集合法 长度OK
aaaaaaaaaaaaaaaaaaaaaaa... 字符数=129 字节数=129 字符集合法 长度超限
中中中中中中中中中中中中中中中中中中中中中中中... 字符数=43 字节数=129 字符集非法 长度超限
注意『中』*43:43 个字符看着远不到 128,字节数已是 129 —— 超了。
而中文本身就不在允许字符集里,所以中文 task_id 是双重违规。
两个可直接用的结论:
审批_20261119_001只有 15 个字符,却是 19 字节。UTF-8 下一个汉字 3 字节,所以「128 字节」实际能放的汉字远少于 128 个。凡是官方写「字节」的地方,都别用len()直接判。- 中文和空格都不在允许字符集里。用业务单号做
task_id时,如果单号含中文前缀(比如「请假-2026-001」),必须先转成纯 ASCII。
正确的写法是用 encode 后取长度:
TASK_ID_RE = re.compile(r"^[A-Za-z0-9_\-@]+$")
TASK_ID_MAX_BYTES = 128
def blen(s):
"""官方约束按字节算,不是按字符。中文一个字 3 字节,这点极易踩。"""
return len((s or "").encode("utf-8"))
同样的字节口径也适用于按钮 key(≤1024 字节)、question_key(≤1024 字节)、选项 id(≤128 字节)。
四、五种卡片的最小合法配置
先给能过校验的最小骨架,再讲各自的坑。校验结果:
== 1. 五种卡片最小合法配置:逐个过校验 ==
text_notice 通过
news_notice 通过
button_interaction 通过
vote_interaction 通过
multiple_interaction 通过
各类型的必填要点(按官方参数表整理)
| card_type | 必填核心 | 最易漏的条件必填 |
|---|---|---|
text_notice | card_action + card_action.type | main_title.title 与 sub_title_text 不可都不填;填了 action_menu 则 task_id 必填 |
news_notice | main_title.title、card_action | card_image 与 image_text_area 必填一个,不可都不填 |
button_interaction | main_title.title、task_id、button_list、button_list.text | type=0 时 key 必填;type=1 时 url 必填 |
vote_interaction | main_title.title、task_id、checkbox、submit_button | checkbox.option_list.id/text/is_checked、submit_button.key |
multiple_interaction | main_title.title、task_id、select_list、submit_button | select_list.question_key 不可重复;submit_button.key |
另外,接收者字段 touser/toparty/totag 在模板卡片参数表里都标「否」,但接口定义章节写明三者不能同时为空。这是典型的「表格看着选填、实际必填」——只按参数表读会漏。
一个反直觉的差异:card_action.type 的取值范围不一样
| card_type | card_action.type 允许值 |
|---|---|
text_notice | [1, 2](1 跳 url,2 打开小程序) |
news_notice | [1, 2] |
button_interaction | 0 / 1 / 2(0 或不填代表不是链接) |
只有按钮交互型允许 type=0。 因为它的点击动作由按钮承载,整张卡可以不是链接。而文本通知型和图文展示型必须整卡可点,所以不允许 0。
拿 button_interaction 的示例去改 text_notice,card_action 照抄 type: 0,就会报错——这是跨类型改配置最常见的翻车点。
列表长度上限,一次记全
| 字段 | 上限 |
|---|---|
button_list | ≤ 6 |
horizontal_content_list | ≤ 6 |
jump_list | ≤ 3 |
vertical_content_list | ≤ 4 |
action_menu.action_list | [1, 3] |
button_selection.option_list | [1, 10] |
select_list(选择器个数) | ≤ 3 |
checkbox.option_list | [1, 20] |
还有一条数值约束容易漏:news_notice 的 card_image.aspect_ratio 必须 大于 1.3 且小于 2.25,不填默认 1.3。注意是开区间——正好填 1.3 或 2.25 都不合规。
五、应用没配回调:JSON 全对也发不出去
这条单独验,因为它最容易被误诊成「字段写错了」。
== 3. 应用没配回调接口:交互卡片根本发不出去 ==
应用已配回调=True -> 通过
应用已配回调=False -> 应用未配置回调接口,不可发送支持回调的卡片(官方明确禁止)
官方原文:没有配置回调接口的应用不可发送支持回调的卡片。
这条是『卡片发不出去』的头号原因,且与 JSON 写得对不对无关。
校验器里对应的判断是这样写的——注意它把「填了 action_menu 的通知型」也算进支持回调:
INTERACTIVE = {"button_interaction", "vote_interaction", "multiple_interaction"}
# 回调前置条件:没有配置回调接口的应用不可发送支持回调的卡片
supports_callback = ct in INTERACTIVE or bool(card.get("action_menu"))
if supports_callback and not app_has_callback:
errs.append("应用未配置回调接口,不可发送支持回调的卡片(官方明确禁止)")
排查顺序建议:先确认应用配了回调,再查字段。 反过来会浪费很多时间——字段改到全对,仍然发不出去。
六、task_id 重复:重发同一张卡的正确做法
官方要求同一应用内 task_id 不能重复。这在「补发」「重推」场景下必然遇到:
== 4. 同应用 task_id 重复:第二次发同一张卡 ==
task_id=leave_001 -> 通过
task_id=leave_001 -> task_id 在本应用内重复:'leave_001'(官方:同一应用不能重复)
task_id=leave_002 -> 通过
幂等设计:task_id 用『业务单号+版本』,重发要换版本号,不能复用。
推荐命名:{业务类型}_{业务单号}_{版本},例如 leave_20261119_001_v2。
这样做的三个好处:
- 重发时递增版本号,天然避开重复约束
- 从
task_id就能反查业务单号,回调回来不用额外查映射 - 同一单据的多个版本可区分,避免「用户点了旧卡片」被当成新审批
注意 task_id 是卡片实例的主键,不是业务单号的主键。一个业务单号可以对应多张卡片(补发、改期),但每张卡片必须有自己的 task_id。
七、12 个配错,校验器逐条拦下
这是本文的核心产出。每个错误都是真实配置里会犯的:
== 2. 十二个真实配错:校验器逐条拦下 ==
task_id 用中文 -> task_id 含非法字符:'请假_001'(只允许数字/字母/_-@)
task_id 带空格 -> task_id 含非法字符:'leave 001'(只允许数字/字母/_-@)
交互卡片漏 task_id -> task_id 缺失(button_interaction 必填)
两个按钮同 key -> button_list[1].key 重复:'same'(官方:不可重复)
7 个按钮 -> button_list 长度 7 > 6
type=0 漏 key -> button_list[0] type=0 但缺 key(条件必填)
type=1 漏 url -> button_list[0] type=1 但缺 url(条件必填)
text_notice 用 type=0 -> card_action.type=0 越界(text_notice 取值范围 [1,2])
news_notice 两图都不填 -> card_image 与 image_text_area 必填一个,不可都不填
宽高比 2.5 越界 -> card_image.aspect_ratio=2.5 越界(须 >1.3 且 <2.25)
4 个选择器 -> select_list 个数 4 > 3(一个消息最多 3 个选择器)
漏 submit_button.key -> multiple_interaction 缺 submit_button.key(必填)
拦下 12 / 12 例
其中**「两个按钮同 key」**最值得单独说。官方明确 button_list.key 不可重复,原因很实际:点击回调把 key 作为 EventKey 原样带回,如果两个按钮同 key,你的后端就无法区分用户点的是「同意」还是「驳回」。
这不是格式洁癖,是业务正确性问题。审批场景下两个按钮同 key,等于同意和驳回走同一个分支。
button_list 的完整校验逻辑:
BUTTON_LIST_MAX = 6 # button_list 列表长度不超过 6
KEY_MAX_BYTES = 1024 # button_list.key 最长 1024 字节
bl = card.get("button_list") or []
if not bl:
errs.append("button_list 缺失或为空(必填)")
if len(bl) > BUTTON_LIST_MAX:
errs.append("button_list 长度 %d > %d" % (len(bl), BUTTON_LIST_MAX))
keys = []
for i, b in enumerate(bl):
if not b.get("text"):
errs.append("button_list[%d] 缺 text(必填)" % i)
bt = b.get("type", 0) # 0 或不填 = 回调;1 = 跳转 url
if bt == 0:
k = b.get("key")
if not k:
errs.append("button_list[%d] type=0 但缺 key(条件必填)" % i)
else:
if blen(k) > KEY_MAX_BYTES:
errs.append("button_list[%d].key 超 %d 字节" % (i, KEY_MAX_BYTES))
if k in keys:
errs.append("button_list[%d].key 重复:%r(官方:不可重复)" % (i, k))
keys.append(k)
elif bt == 1:
if not b.get("url"):
errs.append("button_list[%d] type=1 但缺 url(条件必填)" % i)
else:
errs.append("button_list[%d].type=%r 非法(0 回调 / 1 跳转)" % (i, bt))
注意 bt = b.get("type", 0) 这行:官方规定「0 或不填代表回调」,所以缺省值必须是 0,不能是 None 或 1。缺省值取错,会把「没写 type 的回调按钮」误判成跳转按钮,然后要求它填 url——校验器自己就成了 bug 源。
八、一份可直接用的按钮交互卡片 JSON
已过校验,把 agentid、touser、域名换成你自己的即可:
{
"msgtype": "template_card",
"agentid": 1000088,
"touser": "ZhangSan",
"card_type": "button_interaction",
"task_id": "leave_20261119_001",
"main_title": {
"title": "请假审批",
"desc": "张三 11/20 全天"
},
"sub_title_text": "事由:家中有事,工作已交接给李四",
"horizontal_content_list": [
{ "keyname": "申请人", "value": "张三" },
{ "keyname": "时长", "value": "1 天" }
],
"button_list": [
{ "text": "同意", "style": 1, "key": "approve" },
{ "text": "驳回", "style": 2, "key": "reject" },
{ "text": "看详情", "type": 1, "url": "https://example.com/leave/1" }
],
"card_action": { "type": 0 }
}
三个设计点值得注意:
- 前两个按钮不写
type(默认 0 = 回调),第三个写type: 1跳详情页。同一张卡里混用回调按钮和跳转按钮是允许的,这比「全部回调再后端重定向」省一次往返。 card_action.type = 0:整卡不做链接,点击动作全交给按钮。这是button_interaction独有的取值。key用语义化英文(approve/reject),不用btn1/btn2。回调回来EventKey直接可读,排查日志时省一层翻译。
style 可填 1~4,不填或错填默认 1。官方文档只给了样式示意图,没有逐一文字描述各值外观,所以配色效果建议实际发一张测试卡看,不要凭数字猜。
九、OA / 低代码平台推审批卡片,怎么套这套规则
如果你的场景是「OA 系统(泛微、致远这类)或低代码平台,通过企微机器人推审批卡片」,本节讲通用做法。
先说清一个区别,这里最容易走错路:
| 通道 | 能不能发模板卡片 | 说明 |
|---|---|---|
| 群机器人 webhook | 不能 | webhook 支持文本/markdown/图片/图文等,模板卡片不在其列 |
自建应用 message/send | 能 | 本文讲的 template_card 走这条 |
所以「机器人推审批卡片」这个说法里,如果指的是群机器人 webhook,那是发不出模板卡片的——需要改用自建应用消息,或者退化成 markdown 消息 + 跳转链接。这一步选错,后面字段配得再对也没用。
至于具体 OA 产品的对接配置项在哪个菜单、叫什么名字,本文不写:我没有实际访问过对应产品的配置界面,写了就是编。这部分请以你使用的 OA 版本官方文档为准。能确定的是出口侧的约束是统一的——不管上游是哪个系统,最终都要落到本文这套企微字段规则上。
通用集成路径,三步:
- OA 侧产生审批事件 → 取出业务单号、申请人、金额/时长等字段
- 中间层组装卡片 JSON → 用本文校验器过一遍,
task_id用{类型}_{单号}_{版本} - 调自建应用
message/send→ 记下返回的response_code(仅支持回调的卡片返回,72 小时内有效、只能调用一次接口)
第 3 步那个 response_code 是后续更新卡片的唯一凭据,发完必须落库。它一次性、有时效,丢了就没法原地更新卡片,只能另发一张新的。至于点击回调之后怎么做幂等核销与卡片更新,那是另一套状态机,本文不展开——提示岛(prompts.ssjintaitong.com)站内 id=12614 收录了那部分的完整实现,本文与它互补:那篇讲收到点击之后,本篇讲发出之前。
还有一条容量约束,做批量推送前必须知道。官方对发送应用消息整体的频率限制:
- 每应用不超过 账号上限数 × 200 人次/天
- 对同一成员不超过 30 次/分钟、1000 次/小时,超出丢弃
「超出丢弃」意味着不报错也不补发。 批量推审批卡片时,如果某个审批人短时间内被推了 30 张以上,多出来的会静默消失。这类问题在日志里看不到失败记录,只能靠对账发现——发送侧要自己记账。
十、发送前排查表
| 现象 | 大概率原因 | 先查什么 |
|---|---|---|
| 交互卡片直接发不出 | 应用未配回调接口 | 应用后台回调 URL 是否配好并验签通过 |
| 卡片在某些客户端不显示 | 版本不够 / 微工作台 | 投票与多项选择需 3.1.12+;微工作台不支持模板卡片 |
| 报 task_id 相关错误 | 含中文/空格,或超 128 字节 | 用 encode 后算字节,字符集只留数字字母 _-@ |
| 重发同一单据失败 | task_id 在同应用内重复 | 加版本号后缀 |
| 点同意和驳回走同一分支 | 两个按钮 key 相同 | key 必须唯一且语义化 |
| 按钮点了没回调 | 该按钮 type=1 是跳转 | 回调按钮 type 应为 0 或不填 |
| 跳转按钮报错 | type=1 但没填 url | 条件必填 |
| text_notice 报 card_action 错 | 照抄了 button_interaction 的 type=0 | 通知型/图文型只允许 [1,2] |
| news_notice 报缺字段 | 两个图字段都没填 | card_image 与 image_text_area 至少填一个 |
| 图片比例报错 | aspect_ratio 越界或取了端点值 | 须严格 >1.3 且 <2.25 |
| 报列表超长 | 按钮 >6 / 选择器 >3 | 对照第四节上限表 |
| touser 为空却以为选填 | 参数表标「否」但接口要求三选一 | touser/toparty/totag 不可同时为空 |
| 批量推送部分人没收到 | 触发同成员 30 次/分钟上限,超出丢弃 | 发送侧自己记账对账 |
| 想原地更新卡片却没有 code | 发卡时未落库 response_code | 该 code 72 小时有效且仅一次,必须发完就存 |
| 群机器人 webhook 发卡片失败 | webhook 不支持模板卡片 | 改走自建应用 message/send |
十一、你手上现在有什么
- 一张五类型必填对照表——知道哪个字段在哪种卡片下必填、条件必填、不存在。
- 一个发送前校验器——纯标准库,12 个常见配错全部拦下,五种最小合法配置全部通过。
- 一份可直接改用的按钮交互卡片 JSON——混用回调按钮与跳转按钮,已过校验。
- 两条容量红线——同成员 30 次/分钟、1000 次/小时,超出静默丢弃。
最该带走的一句:先确认应用配了回调、通道选的是自建应用消息,再去抠字段。 顺序反了,会在字段上白耗很久。
下一篇回到 DSH 生态,讲另一类「装了但没生效」的问题:插件的发布年龄门槛与版本核对——那层的坑是命令显示成功,装的却是旧版。
十二、参考与说明
字段约束来源:企业微信开发者中心官方文档「发送应用消息」(developer.work.weixin.qq.com/document/path/90236),2026-11-19 直接访问核对,页面标注最后更新 2025/09/24。本文的五种 card_type 取值、task_id 字符集与 128 字节上限、button_list ≤6 与 key ≤1024 字节不可重复、card_action.type 分类型取值范围、各列表长度上限、aspect_ratio 开区间、response_code 72 小时一次性、版本要求、微工作台限制、未配回调不可发送、频率限制——逐条取自该页原文。
边界与置信说明:
- 校验器本地真跑,12/12 拦下、五种最小配置全通过,但它没有真实调用企微接口发送消息。它校验的是「按官方文档规则该不该过」,不等于企微服务端的实际校验结果。服务端可能有文档未列出的额外校验,以实际返回为准。
- 示例中的
agentid=1000088、touser=ZhangSan、example.com域名、请假事由均为占位数据,不含任何真实企业信息。 - 官方文档未写明、本文因而不作推断的点:
button_selection顶层是否必填(文档只列了其子字段必填性);vote_interaction/multiple_interaction是否支持card_action(参数表未列出);button_list.style1~4 各自的具体外观(仅图示,无文字描述)。这几处请以实际测试或官方最新页面为准。 - 泛微等具体 OA 产品的配置界面与菜单路径,本文未涉及,因为没有实际访问核实。第九节只给与产品无关的通用出口约束。
- 文档内容可能更新,涉及生产配置请以企业微信开发者中心当前页面为准。
DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。
更多推荐

所有评论(0)