Zoom Team Chat 消息卡片结构详解Chatbot API 富交互消息的 JSON 设计与实战【免费下载链接】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导读本文聚焦 Zoom Team Chat 集成中 Chatbot API机器人类型的核心能力——消息卡片Message Card讲解其类卡片 JSON 结构content.head与content.body的完整设计、全部组件类型、交互机制与常见坑点。阅读后你将能独立构造包含标题、文本、键值字段、按钮、下拉框、表单与图片附件的富交互消息并通过POST /v2/im/chat/messages发送给用户再借助interactive_message_actions交互 Webhook 处理用户点击。相关权威素材见 Message Card Components Reference 与 Message Card Structure概念文档。一、消息卡片的高层形态Zoom Team Chat 的 Chatbot 消息使用一种卡片化的 JSON 结构业界常称 message cards。与 Team Chat API用户类型走POST /v2/chat/users/me/messages发送纯文本message字段不同Chatbot API 发送的是结构化content对象这是富交互能力的根基。从 message-structure.md 可以看到核心骨架content.head → 标题 可选副标题 content.body → 组件数组blocks ├── message 文本块 ├── fields 键/值行 ├── actions 按钮块 └── attachments 图片/链接块对应的最小 JSON 骨架如下来自 message-cards.md{ content: { head: { // 可选头部 text: Title, sub_head: { text: Subtitle } }, body: [ // 组件数组 { type: message, text: Content }, { type: actions, items: [...] } // ... 更多组件 ] } }要点head是可选头部text为主标题sub_head.text为副标题body是组件数组每个元素通过type字段声明类型可自由组合、有序排列head与body可同时省略其一但实际使用中至少应包含body否则卡片没有可展示内容。二、组件目录Components Catalog2.1 文本类组件message—— 纯文本内容{ type: message, text: Hello, this is plain text }header—— 带可选样式的标题文本{ type: header, text: Main Heading, style: { bold: true, italic: false } }styled_text—— 支持 Markdown 风格样式的文本**Bold**加粗、*italic*斜体、code行内代码{ type: styled_text, text: **Bold** *italic* code }2.2 交互类组件actions按钮—— 可点击按钮点击后触发交互 Webhook{ type: actions, items: [ { text: Approve, value: approve, style: Primary // Primary, Danger, Default }, { text: Reject, value: reject, style: Danger } ] }按钮样式style三选一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 }2.3 布局类组件section—— 组件分组支持可选的彩色侧边栏sidebar{ 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 }2.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 } } }三、完整实战示例3.1 构建通知Build Notification{ 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 } ] } ] } }3.2 审批请求Approval Request{ 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 } ] } ] } }3.3 错误通知Error Notification{ 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 } ] } ] } }四、如何发送卡片消息Chatbot API 调用卡片 JSON 只是content字段发送时需封装进 Chatbot API 请求体中。在 SKILL.md 与 chatbot-setup.md 中给出了完整调用范式const response await fetch(https://api.zoom.us/v2/im/chat/messages, { method: POST, headers: { Authorization: Bearer ${accessToken}, // client_credentials 换取 Content-Type: application/json }, body: JSON.stringify({ robot_jid: process.env.ZOOM_BOT_JID, // Marketplace → Features → Chatbot → Bot Credentials to_jid: payload.toJid, // 来自 Webhook payload account_id: payload.accountId, // 来自 Webhook payload content: { head: { text: Build Notification, sub_head: { text: CI/CD Pipeline } }, body: [ { type: message, text: Deployment successful! }, { type: fields, items: [ { key: Branch, value: main }, { key: Commit, value: abc123 } ] }, { type: actions, items: [ { text: View Logs, value: view_logs, style: Primary }, { text: Dismiss, value: dismiss, style: Default } ] } ] } }) });字段说明robot_jid机器人 JID格式如v1abc123xyzxmpp.zoom.us在 Zoom Marketplace 的 Bot Credentials 中获取to_jid/account_id来自bot_notificationWebhook payload用于定位接收者content即上文讲解的完整卡片对象令牌获取使用client_credentials授权模式POST https://zoom.us/oauth/tokengrant_typeclient_credentialsBasic Auth 携带CLIENT_ID:CLIENT_SECRET对应 scope 为imchat:bot自动添加。注意两种 API 不可混用Team Chat API 走POST /v2/chat/users/me/messages发送的是用户身份的纯文本不支持富卡片只有 Chatbot API/v2/im/chat/messages支持按钮、表单、下拉框、图片等富交互组件。若选错类型认证方式、scope、端点全家不匹配。参见 api-selection.md。五、交互闭环按钮点击与 value 路由消息卡片的价值在于交互。在 message-structure.md 中明确强调按钮必须携带一个可用于路由的value——当你收到交互 Webhook 时正是靠它来区分用户点了哪个按钮。交互流程来自 button-actions.md你发送一张包含actions.items[]的卡片每个按钮带唯一value用户点击后Zoom 向你的 Bot Endpoint URL 发送interactive_message_actionsWebhook你的 handler 依据actionItem.value路由处理。路由建议使用稳定、语义化的 action ID例如approve_request、reject_request、open_ticket:123避免使用易变的展示文本做路由键。服务端处理示例来自 SKILL.mdcase interactive_message_actions: { const { actionItem, toJid, accountId } payload; if (actionItem.value approve) { await sendChatbotMessage(toJid, accountId, { body: [{ type: message, text: ✅ Approved! }] }); } }在完整实现中见 chatbot-setup.md 的utils/chatbot.js还可以封装sendMessageWithButtons()帮助函数把按钮数组批量映射为actions.items并默认style: Default从而保证每张卡片都能被统一、安全地构造。六、组件限制Limitations构造卡片前请务必对照容量上限避免发送被拒或渲染异常组件限制消息文本4,096 字符按钮文本40 字符字段键/值各 256 字符下拉框选项100 个每条消息按钮5 个在 chatbot-setup.md 的utils/validation.js中还提供了一种防御性写法发送前对文本执行trim()、移除控制字符/[\x00-\x1F\x7F]/g并substring(0, 4096)截断从源头规避长度超限问题。七、最佳实践7.1 按钮文案设计✅推荐使用清晰、面向动作的标签Approve RequestView DetailsCancel Order❌避免语义模糊的标签OKClick HereButton7.2 配色语义化✅推荐使用语义色绿色#10b981表示成功红色#ef4444表示错误/破坏性操作蓝色#3b82f6表示信息橙色#f59e0b表示警告❌避免无意义的随意配色。7.3 字段格式✅推荐键保持简洁、值提供信息量{ key: Status, value: Active }❌避免键过长{ key: The current status of the request, value: Active }八、常见坑与排障Common Pitfallsmessage-structure.md 与 message-issues.md 共同总结了高频问题按钮缺少value或 value 不可路由交互 Webhook 到来时无法确定用户意图导致点击无响应。务必为每个按钮设置稳定唯一的value。Zoom 没有渲染我的卡片往往是 JSON 形状非法发送前先校验 payload。做法是先对照已知可用的示例精简到最小卡片再逐步增量添加组件定位出错的组件。消息发不出去确认使用的 API 与令牌匹配——Team Chat API 用用户 OAuth 令牌Chatbot API 用机器人令牌并携带robot_jid确认ZOOM_BOT_JID与ZOOM_ACCOUNT_ID正确。收到endpoint.url_validation却校验失败确保你的端点按规范返回plainTokenencryptedToken用ZOOM_VERIFICATION_TOKEN做 HMAC-SHA256 加密。Webhook 签名校验所有交互请求都应校验x-zm-signature头v0:${timestamp}:${JSON.stringify(body)}的 HMAC-SHA256 摘要防止伪造请求。九、测试卡片与后续进阶在线预览可借助 Zoom 官方的 Team Chat App Card Builderappssdk.zoom.us/cardbuilder预览卡片设计、测试布局、生成 JSON——发送前先用它验证结构是最稳妥的实践。最小冒烟测试参照 get-started.md 的第 4 步先用body: [{ type: message, text: ... }]发送一条纯文本机器人消息确认链路打通后再叠加按钮、表单等高级组件。继续深入处理按钮点击的完整工程见 button-actions.md理解bot_notification、interactive_message_actions、chat_message.submit等全部事件见 webhook-events.md从零搭建带 Webhook、签名校验与命令路由的完整机器人见 chatbot-setup.md。十、组件速查表组件用途关键字段header标题与副标题text、stylemessage纯文本textfields键值对items[].key/valueactions按钮items[].text/value/stylesection彩色侧边栏分组sidebar_color、sectionsattachments图片与链接img_url、resource_urldivider水平分隔线无form_field文本输入editable、textdropdown选择菜单select_items[]date_picker日期选择—掌握head body 组件数组这一核心形态配合完整的组件目录、交互 Webhook 路由与容量限制即可在 Zoom Team Chat 中构建出 CI/CD 通知、审批流、服务告警、LLM 对话助手等各类富交互机器人体验。【免费下载链接】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），仅供参考