Zoom Team Chat 消息卡片组件完整指南用 JSON 构建丰富交互式 Chatbot 消息【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本指南以 message-cards.md 为核心系统讲解 Zoom Team Chat Chatbot API 的消息卡片Message CardJSON 结构、全部组件类型、按钮/下拉/表单等交互元素、布局与媒体组件、完整实战示例、硬性限制与设计最佳实践。读完本文你将能够独立构造从 CI/CD 构建通知到审批流、错误告警在内的各类富交互卡片并能在仓库配套的 Chatbot Setup 完整示例 基础上直接落地发送与回调处理。一、消息卡片与 Chatbot API 的定位在 Zoom Team Chat 中存在两种消息能力而消息卡片是Chatbot APIBot 身份专属的富交互能力这一点必须首先明确详见 SKILL.md 中的 API 决策表Team Chat API用户身份以认证用户的身份发普通文本消息走POST /v2/chat/users/me/messages使用 User OAuthauthorization_code不支持富卡片。Chatbot APIBot 身份以 Bot 身份发送含按钮、表单、下拉、图片的富卡片走POST /v2/im/chat/messages使用 Client Credentialsclient_credentialsScope 为imchat:bot。因此凡是需要按钮、表单、下拉选择、富文本卡片的场景都必须选择 Chatbot API。从源码结构看本仓库的团队聊天技能将 message-cards.md 定位为 Chatbot API 的“完整卡片组件参考”并配套了 卡片结构概念说明、按钮动作示例、下拉选择示例 与 表单提交示例 等深度材料共同构成一条完整的“构造卡片 → 发送 → 处理回调”链路。二、卡片总体结构content 的 head 与 body每一条 Chatbot 消息本质是一份 JSON最外层是content对象包含可选的头部head与组件数组body{ content: { head: { // 可选头部 text: Title, sub_head: { text: Subtitle } }, body: [ // 组件数组 { type: message, text: Content }, { type: actions, items: [...] } // ... 更多组件 ] } }对应地message-structure.md 将高层结构概括为content.head标题 可选副标题content.body块block数组其中message块承载文本、fields块承载键值行、actions块承载按钮、attachments块承载图片/链接。常见陷阱很多“卡片没有渲染”的问题根因其实是 JSON 结构不合法字段名拼错、数组/对象嵌套层级错误等务必在发送前校验 payload见 message-issues.md 的“最小化卡片、逐步添加组件”排查法。三、组件目录文本、交互、布局与媒体3.1 文本组件message纯文本最基础的正文组件。{ type: message, text: Hello, this is plain text }header标题文本带可选样式粗体/斜体的标题。{ type: header, text: Main Heading, style: { bold: true, italic: false } }styled_text富文本支持 Markdown 风格样式**加粗**、*斜体*、代码。{ type: styled_text, text: **Bold** *italic* code }3.2 交互组件actions按钮可点击按钮点击后触发 webhook对应interactive_message_actions事件。每个按钮包含text显示文本、value路由标识必须全局稳定与style视觉样式。{ type: actions, items: [ { text: Approve, value: approve, style: Primary // Primary, Danger, Default }, { text: Reject, value: reject, style: Danger } ] }按钮样式Primary- 蓝色按钮代表主要/推荐操作Danger- 红色按钮代表破坏性/拒绝操作Default- 灰色按钮代表中性操作。dropdown下拉菜单可选项列表适合让用户在预定义集合中选择。{ type: dropdown, select_items: [ { text: Option 1, value: opt1 }, { text: Option 2, value: opt2 } ] }form_field文本输入框卡片内收集用户自由文本输入。{ type: form_field, editable: true, text: Enter your name }3.3 布局组件section分组容器将一组组件分组支持可选彩色侧边栏sidebar_colorHex 色值。{ type: section, sidebar_color: #3b82f6, // Hex 颜色 sections: [ { type: message, text: Grouped content } ] }常用语义色语义色值用途Success#10b981绿成功/完成Error#ef4444红错误/失败Warning#f59e0b橙警告/待关注Info#3b82f6蓝信息提示fields键值对以列形式展示键值对适合呈现状态、优先级、负责人等结构化信息。{ type: fields, items: [ { key: Status, value: Active }, { key: Priority, value: High }, { key: Assignee, value: John Doe } ] }divider分割线水平分隔线用于在视觉上区分卡片区块。{ type: divider }3.4 媒体组件attachments图片附件展示图片可选关联跳转链接与标题/描述信息。{ type: attachments, img_url: https://example.com/image.jpg, resource_url: https://example.com/full-page, information: { title: { text: Image Title }, description: { text: Click to view } } }四、完整实战示例4.1 构建通知Build Notification组合section绿色侧边栏、fields构建信息与actions操作按钮即典型 CI/CD 通知卡片{ content: { head: { text: Build #123 Complete, sub_head: { text: main branch } }, body: [ { type: section, sidebar_color: #10b981, sections: [ { type: message, text: ✅ Build completed successfully } ] }, { type: fields, items: [ { key: Branch, value: main }, { key: Commit, value: abc123 }, { key: Duration, value: 2m 34s } ] }, { type: actions, items: [ { text: View Logs, value: view_logs, style: Primary }, { text: Deploy, value: deploy, style: Default } ] } ] } }4.2 审批请求Approval Request典型的审批流卡片head说明主题 →message交代事由 →fields展示金额/类别/日期 →divider分隔 →actions提供 ApprovePrimary/ RejectDanger/ View DetailsDefault三种操作每种操作通过唯一value区分{ content: { head: { text: Expense Approval Required }, body: [ { type: message, text: John Doe submitted an expense report }, { type: fields, items: [ { key: Amount, value: $500.00 }, { key: Category, value: Travel }, { key: Date, value: Feb 9, 2026 } ] }, { type: divider }, { type: actions, items: [ { text: Approve, value: approve_500, style: Primary }, { text: Reject, value: reject_500, style: Danger }, { text: View Details, value: details_500, style: Default } ] } ] } }4.3 错误通知Error Notification红色#ef4444section强调错误主体fields给出服务名、错误信息与时间actions提供 View Logs / Acknowledge{ content: { head: { text: ⚠️ Service Alert }, body: [ { type: section, sidebar_color: #ef4444, sections: [ { type: message, text: Database connection failed } ] }, { type: fields, items: [ { key: Service, value: api-prod }, { key: Error, value: Connection timeout }, { key: Time, value: 2026-02-09 18:30:00 UTC } ] }, { type: actions, items: [ { text: View Logs, value: logs, style: Primary }, { text: Acknowledge, value: ack, style: Default } ] } ] } }五、硬性限制卡片各字段的长度与数量上限构建卡片前必须熟记以下限制否则消息会被拒绝或截断组件限制消息文本4,096 字符按钮文本40 字符字段键/值各 256 字符下拉选项100 个选项每条消息按钮数5 个按钮这解释了仓库 chatbot-setup.md 中sanitizeMessage函数的设计动机它对消息做trim()、移除控制字符[\x00-\x1F\x7F]并强制截断到 4096 字符——在发送端就守住消息长度上限。同时 SKILL.md 的限制表 也再次确认消息长度上限为 4,096 字符。六、最佳实践可读性、语义色与路由设计6.1 按钮文案✅应该使用清晰、面向动作的标签Approve RequestView DetailsCancel Order❌不要使用模糊标签OKClick HereButton这与 button-actions.md 的路由建议一致为每个按钮使用稳定的动作 ID如approve_request、reject_request、open_ticket:123这样在interactive_message_actionswebhook 中才能依据actionItem.value精确路由到对应处理逻辑参见 chatbot-setup.md 中的 handleButtonClick 实现。6.2 颜色语义✅应该使用有语义的颜色绿色#10b981表示成功红色#ef4444表示错误/破坏性动作蓝色#3b82f6表示信息橙色#f59e0b表示警告❌不要随意使用没有含义的颜色。6.3 字段格式✅应该键保持简洁值承载信息{ key: Status, value: Active }❌不要键写得太长{ key: The current status of the request, value: Active }结合字段 256 字符上限第五节过长的键既影响列布局可读性也极易触碰长度限制。6.4 校验与调试message-issues.md 给出两类高频问题的处置方向消息发不出去确认是否用了正确的 API——Team Chat API 用用户 OAuth tokenChatbot API 用 bot token robot_jid详见 chatbot-setup.md 的 sendChatbotMessage它同时携带robot_jid、to_jid、account_id与content四要素卡片不渲染先用已知正确的示例校验 JSON再把卡片简化为最小形态逐个增量添加组件定位问题。七、端到端落地从卡片 JSON 到发送与回调消息卡片最终通过POST https://api.zoom.us/v2/im/chat/messages发送。仓库 chatbot-setup.md 提供了完整的生产级参考实现其中封装了三个典型发送函数可直接映射到本指南的卡片结构sendTextMessagebody中仅含{ type: message, text }sendMessageWithButtonshead.text为标题body依次为message与actions按钮由调用方传入{ text, value, style }映射生成sendMessageWithFieldsbody中为fields组件由{ key, value }映射生成。交互闭环如下按钮动作模式发送含actions.items[]的卡片每个按钮带唯一value用户点击按钮Zoom 向你的 webhook 发送interactive_message_actions事件处理器依据actionItem.value路由处理。完整的事件类型与处理清单见 webhook-events.md包括bot_notification用户消息/命令、interactive_message_actions点击按钮、chat_message.submit提交表单、bot_installed安装与app_deauthorized卸载。处理回调时的通用原则是先验签、把 payload 当作不可信输入解析、按事件类型与动作值路由、尽快响应耗时工作异步处理。八、测试卡片与后续学习路径测试工具Zoom 提供 Team Chat App Card Builder可视化卡片设计器可用来预览卡片设计、测试布局并生成 JSON是开发阶段最直接的验证手段定位 JSON 问题时也可对照本指南第四节的三个完整示例逐字段比对。继续深入阅读以下均为仓库内已存在路径Chatbot Setup 完整示例从零构建首个可运行 Chatbot含鉴权、验签、webhook 路由与 ngrok 本地测试按钮动作处理按钮点击 webhook 的取值路由Webhook 事件参考各类事件 payload 与处理清单消息卡片结构概念卡片组件的层级关系与常见陷阱Team Chat 技能总览API 选型、环境变量、安全最佳实践与完整文档索引。掌握本指南的组件目录、三个完整示例与限制表后再配合上述示例即可在 Zoom Team Chat 中交付从“纯文本通知”到“按钮驱动的审批工作流”的完整交互体验。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考