Zoom Team Chat 斜杠命令Slash Command实战指南从 Marketplace 配置到 Webhook 处理【免费下载链接】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导读斜杠命令Slash Command是 Zoom Team Chat 中用户触发聊天机器人的标准交互入口用户输入/yourcommand即可唤起你的 BotZoom 会以 Webhook 事件的形式把命令文本推送到你的服务端。本文基于 knowledge-work-plugins 仓库中的 Slash Commands 示例文档 展开系统讲解斜杠命令的配置位置、完整调用链路bot_notificationWebhook、参数解析与消息卡片响应并结合同仓库的 Webhook 架构、Chatbot 完整示例 等文档补充可运行的代码与排查清单。读完本文你将能独立实现一个配置命令 → 接收命令 → 解析参数 → 卡片回复的完整斜杠命令机器人并规避常见的账户作用域与服务端解析陷阱。一、斜杠命令是什么Chatbot API 的交互入口在 Zoom Team Chat 的集成体系中有两条截然不同的 API 路线斜杠命令只属于 Chatbot APIBot 类型这一点必须先确认否则后续的鉴权、作用域、端点全部对不上集成类型鉴权方式端点家族消息呈现身份是否支持斜杠命令Team Chat API用户类型User OAuthauthorization_code/v2/chat/users/...已认证的真实用户❌Chatbot APIBot 类型Client Credentialsclient_credentials/v2/im/chat/messages你的 Bot 身份✅完整的选择依据可参考 API 选择指南需要富交互消息按钮、表单、下拉框、需要处理用户交互、需要响应斜杠命令的场景一律走 Chatbot API而仅需以用户身份发纯文本通知的场景如 CI/CD 通知才使用 Team Chat API。错误地混用用户类型鉴权 Bot 端点是社区中最常见的实现失败原因。二、斜杠命令的工作模式Pattern原文档给出了斜杠命令的四步标准模式这是理解整个机制的主线在 Chatbot 功能设置Marketplace 应用的Features → Team Chat Subscription中配置/yourcommand用户在 Team Chat 中输入并运行该命令你的 Webhook 端点收到bot_notification或等价事件载荷中包含命令文本在服务端解析命令参数并以消息卡片Message Card回复。2.1 底层链路一次完整的命令往返结合 Webhook 架构文档 中的示例流程一次斜杠命令的完整往返如下1. 用户在 Zoom Team Chat 输入 /weather San Francisco 2. Zoom 向你的 Bot Endpoint URL 发送 POST 请求 3. 服务端收到 Webhookpayload.cmd San Francisco 4. 服务端调用天气 API或 LLM 5. 服务端通过 /v2/im/chat/messages 回发携带天气数据的聊天消息关键点是斜杠命令本身只是一个触发器真正的命令处理、参数解析、业务逻辑与回复组装全部发生在你的服务端Zoom 只负责把用户的命令文本原样投递给你。2.2bot_notification事件载荷解析当用户通过斜杠命令或直接私信与 Bot 交互时Zoom 发送的bot_notification事件体结构如下来自 Webhook 架构文档{ event: bot_notification, payload: { accountId: ..., toJid: channelconference.xmpp.zoom.us, // 回复应发往的位置频道或私聊 robotJid: botxmpp.zoom.us, userJid: userxmpp.zoom.us, cmd: users input text, // 用户输入的命令文本 userName: John Doe, channelName: Marketing, timestamp: 1234567890 } }对斜杠命令处理而言三个字段最关键cmd用户在斜杠命令后输入的内容即你需要在服务端解析的参数。例如用户输入/mybot help则cmd为helptoJid回复的目标地址频道 JID 或私聊 JID回发消息时必须原样带上accountId账户标识回发消息时同样必填。完整的 Webhook 事件清单endpoint.url_validation、bot_installed、bot_notification、interactive_message_actions、app_deauthorized等可参考 Webhook 事件参考。三、前置条件应用创建与斜杠命令配置斜杠命令是在 Marketplace 应用上配置的而不是写死在代码里的。因此第一步是创建正确的应用类型并开启对应功能详细步骤见 环境搭建指南这里给出与斜杠命令直接相关的要点3.1 应用类型与账号权限必须是General App (OAuth)切勿选择 Server-to-Server OAuth——后者不支持 Chatbot / Team Chat 功能需要 Zoom 账号的 owner、admin 权限或开启Zoom for developers角色路径User Management → Roles → Role Settings → Advanced features。3.2 开启 Team Chat Subscription 并配置命令在应用后台Features → Surface勾选Team Chat然后进入Team Chat Subscription完成两项核心配置字段说明示例Slash Command用户在聊天中调起 Bot 的命令/mybotBot Endpoint URL接收 Webhook 事件的 HTTPS 端点https://yourdomain.com/webhook注意不开启 Team Chat SubscriptionBot 就不会出现在 Team Chat 中斜杠命令自然也无法触发。保存配置后 Zoom 会发送endpoint.url_validation校验请求你的端点需按规则返回plainToken与encryptedTokenHMAC-SHA256 计算成功后会显示绿色勾选。3.3 必备凭据与 .envBot 类型的斜杠命令机器人需要以下凭据获取位置见 环境变量参考变量用途获取位置ZOOM_CLIENT_IDClient Credentials 鉴权身份App Credentials → DevelopmentZOOM_CLIENT_SECRET换取令牌的密钥App Credentials → DevelopmentZOOM_BOT_JIDBot 身份标识格式v1abc123xyzxmpp.zoom.usFeatures → Chatbot → Bot CredentialsZOOM_VERIFICATION_TOKENWebhook 签名校验密钥Features → Team Chat Subscriptions → Secret TokenZOOM_ACCOUNT_ID回发消息时的账户标识App Credentials → Development对应的.env模板ZOOM_CLIENT_IDyour_client_id_here ZOOM_CLIENT_SECRETyour_client_secret_here ZOOM_BOT_JIDv1abc123xyzxmpp.zoom.us ZOOM_VERIFICATION_TOKENyour_webhook_secret_token ZOOM_ACCOUNT_IDyour_account_id PORT4000四、服务端实现解析命令并回复消息卡片4.1 Webhook 处理器中的命令路由斜杠命令到达bot_notification后服务端需要自行解析cmd并路由。仓库中的 Chatbot 完整示例routes/webhook.js给出了一个可直接运行的最小命令路由器async function handleBotNotification(payload, res) { const { toJid, cmd, accountId, userName } payload; console.log(${userName} sent: ${cmd}); // 立即响应避免 Webhook 超时 res.status(200).json({ success: true }); // 异步处理命令 try { if (cmd.toLowerCase().includes(help)) { await sendTextMessage(toJid, accountId, Available commands:\n- help: Show this message\n- ping: Test bot\n- demo: Show demo buttons ); } else if (cmd.toLowerCase().includes(ping)) { await sendTextMessage(toJid, accountId, Pong! ); } else if (cmd.toLowerCase().includes(demo)) { await sendMessageWithButtons(toJid, accountId, { title: Demo Buttons, message: Click a button below:, buttons: [ { text: Option A, value: option_a, style: Primary }, { text: Option B, value: option_b, style: Default }, { text: Cancel, value: cancel, style: Danger } ] }); } else { await sendTextMessage(toJid, accountId, You said: ${cmd}\n\nType help to see available commands. ); } } catch (error) { console.error(Error processing command:, error); } }示例中先立即返回 200、再异步执行业务的写法值得沿用Zoom 期望 Webhook 端点在3 秒内返回 200若在处理器内同步等待慢速的 LLM 调用或外部 API极易超时重试。4.2 参数解析建议示例采用的是includes子串匹配适合演示生产环境建议自行实现更严谨的参数解析例如精确匹配将cmd.trim()按空白字符切分为[command, ...args]首 token 精确匹配命令名剩余部分作为参数列表如/mybot weather San Francisco得到args [San Francisco]大小写归一化统一toLowerCase()后再匹配回退分支始终保留else兜底回复帮助提示让用户知道如何正确使用LLM 路由若命令众多或意图复杂可参考 LLM 集成示例 的推荐流程——接收bot_notification→ 提取用户文本与频道上下文 → 用 LLM 做意图分类 → 执行安全的后端动作 → 将结构化结果回复到 Team Chat。4.3 以消息卡片回复回复内容使用 Chatbot API 的消息卡片结构核心骨架来自 消息卡片参考{ content: { head: { // 可选标题区 text: Title, sub_head: { text: Subtitle } }, body: [ // 组件数组 { type: message, text: Content }, { type: actions, items: [...] } // 按钮等交互组件 ] } }结合 Chatbot 示例 中的sendChatbotMessage封装实际回发代码如下async function sendChatbotMessage(toJid, accountId, content) { const accessToken await getChatbotToken(); // client_credentials 换 token const body { robot_jid: process.env.ZOOM_BOT_JID, to_jid: toJid, account_id: accountId, content: content }; const response await fetch(https://api.zoom.us/v2/im/chat/messages, { method: POST, headers: { Authorization: Bearer ${accessToken}, Content-Type: application/json, }, body: JSON.stringify(body), }); if (!response.ok) { const error await response.json(); throw new Error(Send message error: ${JSON.stringify(error)}); } return response.json(); }其中 token 通过 Client Credentials 获取无需用户登录async function getChatbotToken() { const credentials Buffer.from( ${process.env.ZOOM_CLIENT_ID}:${process.env.ZOOM_CLIENT_SECRET} ).toString(base64); const response await fetch(https://zoom.us/oauth/token, { method: POST, headers: { Authorization: Basic ${credentials}, Content-Type: application/x-www-form-urlencoded, }, body: grant_typeclient_credentials }); if (!response.ok) { const error await response.json(); throw new Error(Token error: ${error.error_description || error.error}); } return (await response.json()).access_token; }回复可按需组合不同卡片组件message纯文本、fields键值对、actions按钮样式为Primary/Danger/Default、section带彩色侧栏的分组、dropdown下拉选择等完整组件目录见 消息卡片参考。五、两大陷阱Pitfalls原文档明确警告了两个容易踩坑的点务必在实现阶段就规避5.1 命令是账户级作用域Account-Scoped的斜杠命令按账户生效而不是按频道或按应用实例全局生效。因此测试时确认你所在的账号正是配置了命令的应用账号Beta 应用只能被开发者所属 Zoom 账号的成员安装这是平台的安全限制见 环境搭建指南在另一个账号下运行命令很可能出现命令不存在或 Bot 无响应这不是代码 bug而是作用域问题多账号部署时需为每个账号完成安装授权流程Local Test 页面的Add App Now → Allow。5.2 不要依赖客户端解析在服务端解析禁止在前端/客户端做命令文本的解析与校验。理由在于Zoom 推送的是 Webhook 事件命令处理必须发生在你的服务端客户端解析结果不可信、不可审计且无法复用给其他客户端桌面端、移动端从安全角度看Webhook 载荷应视为不可信输入——Webhook 事件参考 的处理清单明确要求仔细解析 payload将其视为不可信输入。正确的做法是服务端完成签名校验 → 提取cmd→ 解析参数 → 路由执行 → 通过/v2/im/chat/messages回发。六、安全加固签名校验与输入消毒斜杠命令 Webhook 是公开可触达的端点必须做好以下防护详见 Webhook 架构文档 与 Chatbot 示例6.1 校验 HMAC-SHA256 签名const crypto require(crypto); function verifyZoomWebhookSignature(req) { const signature req.headers[x-zm-signature]; const timestamp req.headers[x-zm-request-timestamp]; if (!signature || !timestamp) { throw new Error(Missing signature headers); } const message v0:${timestamp}:${JSON.stringify(req.body)}; const hash crypto .createHmac(sha256, process.env.ZOOM_VERIFICATION_TOKEN) .update(message) .digest(hex); if (signature ! v0${hash}) { throw new Error(Invalid webhook signature); } return true; }未经校验的端点任何人都能伪造 Webhook可能触发未授权操作或拒绝服务。仓库文档还提示优先使用 secret token 签名校验旧版 verification token 仅作兼容见 环境变量参考。6.2 消息消毒与 JID 校验// 消息长度限制 4096 字符去除控制字符 function sanitizeMessage(message) { if (typeof message ! string) return ; return message.trim() .replace(/[\x00-\x1F\x7F]/g, ) .substring(0, 4096); } // JID 格式userdomain 或 channeldomain function isValidJID(jid) { if (typeof jid ! string || !jid.trim()) return false; return /^[^\s][^\s]$/.test(jid); }6.3 其他安全要点用环境变量承载凭据绝不硬编码密钥生产环境必须使用 HTTPS 端点对未知事件类型始终提供default分支并返回 200避免新增事件导致崩溃记录 Webhook 活动日志事件类型、时间戳、账户 ID便于排障与审计。七、本地联调与验证7.1 ngrok 暴露本地服务npm install -g ngrok node server.js # 本地服务监听 4000 ngrok http 4000 # 获得 https://abc123.ngrok.io将 HTTPS 地址填入 Marketplace 的Bot Endpoint URL如https://abc123.ngrok.io/webhook保存后触发endpoint.url_validation校验。7.2 冒烟测试清单安装 BotLocal Test → Add App Now → Allow后在任意频道输入/mybot help— 显示帮助消息/mybot ping— 回复 Pong!/mybot demo— 展示带按钮的卡片点击按钮 — 触发interactive_message_actions并返回确认消息若收不到事件可先用 curl 验证端点可达预期返回签名错误属正常现象因为缺少合法签名头curl -X POST http://YOUR_DEV_HOST:4000/webhook \ -H Content-Type: application/json \ -d {event:test}7.3 常见问题速查现象原因处理URL 校验失败响应格式不正确返回plainTokenencryptedToken提示 Invalid signature密钥不匹配核对ZOOM_VERIFICATION_TOKEN与 Marketplace 的 Secret TokenBot 无响应端点 URL 错误或 ngrok 未运行核对 Marketplace 中 URL 与本地进程Webhook 超时处理过慢立即返回 200异步处理命令在其他账号失效命令是账户级作用域确认测试账号为应用所属账号八、进阶从斜杠命令到完整交互机器人斜杠命令通常是交互式机器人的起点。围绕bot_notification事件你可以继续叠加仓库中提供的完整能力矩阵按钮交互回复卡片中的actions组件用户点击后触发interactive_message_actions按actionItem.value路由处理见 Chatbot 示例表单与下拉框form_field、dropdown、date_picker组件配合chat_message.submit事件收集用户输入LLM 增强把cmd直接交给 Claude / GPT 等模型理解意图并生成回复见 LLM 集成示例这是把斜杠命令变成AI 助手最直接的方式多步工作流结合会话状态存储实现审批、任务分配等复杂流程。需要说明的是仓库中的 SKILL.md 是整套 Team Chat 技能文档的导航中枢本文聚焦的 斜杠命令示例 只是其中一环若你从零开始构建建议按API 选择 → 环境搭建 → Chatbot 示例 → Webhook 架构 → 消息卡片的路径阅读完整文档链。结语斜杠命令的本质并不复杂在 Marketplace 配一个命令在服务端收一个bot_notification解析cmd后回一条消息卡片。但要让它在生产环境稳定可靠必须重视三个原则——正确的集成类型Chatbot API Client Credentials、账户级作用域意识、以及全部解析与安全校验都在服务端完成。遵循本文的配置步骤与代码骨架配合仓库中 Chatbot 完整示例 与 Webhook 架构文档 的细节即可快速交付一个可用、可扩展的 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），仅供参考