卡片 JSON 写完,接口调了,返回一个错误码。改一版,再调,换个错误码。

这种来回大部分时候不是因为不懂业务,而是因为模板卡片的必填规则是「按卡片类型分叉」的:同一个字段在 A 类型必填、在 B 类型选填、在 C 类型压根不存在。凭一份通用示例改,很容易改出个四不像。

这篇把五种卡片的必填与条件必填规则列全,给一个发送前就能跑完的校验器,把 12 个常见配错一次拦下。重点在「发出去之前」,不涉及点击回调怎么处理。


一、先分清:五种卡片,只有三种能交互

card_type中文能回调更新版本要求
text_notice文本通知型仅当填了 action_menu3.1.6+
news_notice图文展示型仅当填了 action_menu3.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 是双重违规。

两个可直接用的结论:

  1. 审批_20261119_001 只有 15 个字符,却是 19 字节。UTF-8 下一个汉字 3 字节,所以「128 字节」实际能放的汉字远少于 128 个。凡是官方写「字节」的地方,都别用 len() 直接判。
  2. 中文和空格都不在允许字符集里。用业务单号做 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_noticecard_action + card_action.typemain_title.title 与 sub_title_text 不可都不填;填了 action_menu 则 task_id 必填
news_noticemain_title.title、card_actioncard_image 与 image_text_area 必填一个,不可都不填
button_interactionmain_title.title、task_id、button_list、button_list.texttype=0 时 key 必填;type=1 时 url 必填
vote_interactionmain_title.title、task_id、checkbox、submit_buttoncheckbox.option_list.id/text/is_checked、submit_button.key
multiple_interactionmain_title.title、task_id、select_list、submit_buttonselect_list.question_key 不可重复;submit_button.key

另外,接收者字段 touser/toparty/totag 在模板卡片参数表里都标「否」,但接口定义章节写明三者不能同时为空。这是典型的「表格看着选填、实际必填」——只按参数表读会漏。

一个反直觉的差异:card_action.type 的取值范围不一样

card_typecard_action.type 允许值
text_notice[1, 2](1 跳 url,2 打开小程序)
news_notice[1, 2]
button_interaction0 / 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 版本官方文档为准。能确定的是出口侧的约束是统一的——不管上游是哪个系统,最终都要落到本文这套企微字段规则上。

通用集成路径,三步:

  1. OA 侧产生审批事件 → 取出业务单号、申请人、金额/时长等字段
  2. 中间层组装卡片 JSON → 用本文校验器过一遍,task_id 用 {类型}_{单号}_{版本}
  3. 调自建应用 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

十一、你手上现在有什么

  1. 一张五类型必填对照表——知道哪个字段在哪种卡片下必填、条件必填、不存在。
  2. 一个发送前校验器——纯标准库,12 个常见配错全部拦下,五种最小合法配置全部通过。
  3. 一份可直接改用的按钮交互卡片 JSON——混用回调按钮与跳转按钮,已过校验。
  4. 两条容量红线——同成员 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.style 1~4 各自的具体外观(仅图示,无文字描述)。这几处请以实际测试或官方最新页面为准。
  • 泛微等具体 OA 产品的配置界面与菜单路径,本文未涉及,因为没有实际访问核实。第九节只给与产品无关的通用出口约束。
  • 文档内容可能更新,涉及生产配置请以企业微信开发者中心当前页面为准。
Logo

DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐