build-zoom-team-chat-app

/build-zoom-team-chat-app

Zoom Team Chat 集成的背景参考。当工作流已经明确、尤其是需要区分 Team Chat API 与 Chatbot API 时，再使用本文档。

请先阅读（关键）

存在两种不同的集成类型，二者不可互换：

1. Team Chat API（用户类型）

   • 以真实的已认证用户身份发送消息
   • 使用 User OAuth（authorization_code）
   • 端点系列：/v2/chat/users/...

2. Chatbot API（机器人类型）

   • 以你的机器人身份发送消息
   • 使用 Client Credentials（client_credentials）
   • 端点系列：/v2/im/chat/messages

如果一开始就选错了类型，认证、权限范围和端点都会不匹配，导致实现失败。

官方文档：https://developers.zoom.us/docs/team-chat/
Chatbot 文档：https://developers.zoom.us/docs/team-chat/chatbot/extend/
API 参考：https://developers.zoom.us/docs/api/rest/reference/chatbot/

快速链接

初次使用 Team Chat？请按以下路径操作：

1. 快速开始：端到端的快速路径（用户类型与机器人类型）
2. 选择你的 API：Team Chat API 与 Chatbot API 的对比
3. 环境设置：凭据、权限范围、应用配置
4. OAuth 设置：完整的认证流程
5. 发送第一条消息：可用于发送消息的完整代码

参考资料：

• Chatbot 消息卡片：完整的卡片组件参考
• Webhook 事件：所有 Webhook 事件类型
• API 参考：端点、方法、参数
• 示例应用：10 多个官方示例应用
• 集成索引：参见本文件下方的章节

遇到问题？

• 认证错误 → OAuth 故障排查
• Webhook 未收到事件 → Webhook 设置指南
• 消息无法发送 → 常见问题
• 先进行快速检查 → 5 分钟运行手册

OAuth 端点检查：

• 授权 URL：https://zoom.us/oauth/authorize
• Token URL：https://zoom.us/oauth/token
• 如果 /oauth/token 返回 404 或 HTML，请使用 https://zoom.us/oauth/token。

正在构建交互式机器人？

• 按钮操作：处理按钮点击
• 表单提交：处理表单数据
• 斜杠命令：创建自定义命令

快速决策：使用哪种 API？

使用场景	使用的 API
从脚本/CI/CD 发送通知	Team Chat API
以用户身份自动发送消息	Team Chat API
构建交互式聊天机器人	Chatbot API
响应斜杠命令	Chatbot API
创建带按钮/表单的消息	Chatbot API
处理用户交互	Chatbot API

Team Chat API（用户级）

• 消息显示为由已认证用户发送
• 需要 User OAuth（authorization_code 流程）
• 端点：POST https://api.zoom.us/v2/chat/users/me/messages
• 权限范围：chat_message:write、chat_channel:read

Chatbot API（机器人级）

• 消息显示为由你的机器人发送
• 需要 Client Credentials 授权类型
• 端点：POST https://api.zoom.us/v2/im/chat/messages
• 权限范围：imchat:bot（自动添加）
• 富卡片：按钮、表单、下拉菜单、图片

前置条件

系统要求

• Zoom 账户
• 账户所有者、管理员，或已启用 Zoom for developers 角色
  • 启用方法：用户管理 → 角色 → 角色设置 → 高级功能 → 启用 Zoom for developers

创建 Zoom 应用

1. 前往 Zoom App Marketplace
2. 点击 Develop → Build App
3. 选择 General App（OAuth）

⚠️ 请勿使用 Server-to-Server OAuth：S2S 应用不支持 Chatbot/Team Chat 功能。只有 General App（OAuth）支持聊天机器人。

所需凭据

在 Zoom Marketplace → 你的应用中获取：

凭据	位置	用于
Client ID	App Credentials → Development	两种 API
Client Secret	App Credentials → Development	两种 API
Account ID	App Credentials → Development	Chatbot API
Bot JID	Features → Chatbot → Bot Credentials	Chatbot API
Secret Token	Features → Team Chat Subscriptions	Chatbot API

参见：环境配置指南，了解完整的配置步骤。

快速开始：Team Chat API

以用户身份发送消息：

// 1. Get access token via OAuth
const accessToken = await getOAuthToken(); // See examples/oauth-setup.md

// 2. Send message to channel
const response = await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello from CI/CD pipeline!',
    to_channel: 'CHANNEL_ID'
  })
});

const data = await response.json();
// { "id": "msg_abc123", "date_time": "2024-01-15T10:30:00Z" }

完整示例：发送消息指南

快速开始：Chatbot API

构建一个交互式聊天机器人：

// 1. Get chatbot token (client_credentials)
async function getChatbotToken() {
  const credentials = Buffer.from(
    `${CLIENT_ID}:${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_type=client_credentials'
  });
  
  return (await response.json()).access_token;
}

// 2. Send chatbot message with buttons
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({
    robot_jid: process.env.ZOOM_BOT_JID,
    to_jid: payload.toJid,           // From webhook
    account_id: payload.accountId,   // From webhook
    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' }
          ]
        }
      ]
    }
  })
});

完整示例：聊天机器人设置指南

主要功能

Team Chat API

功能	说明
发送消息	向频道或私信发布消息
列出频道	获取用户的频道及其元数据
创建频道	以编程方式创建公开/私有频道
线程回复	回复线程中的特定消息
编辑/删除	修改或删除消息

Chatbot API

功能	说明
富消息卡片	标题、图片、字段、按钮、表单
斜杠命令	自定义 /commands 触发 Webhook
按钮操作	带 Webhook 回调的交互式按钮
表单提交	通过表单收集用户输入
下拉选择	频道、成员、日期/时间选择器
大模型集成	轻松集成 Claude、GPT 等

Webhook 事件（Chatbot API）

事件	触发条件	使用场景
bot_notification	用户向机器人发送消息或使用斜杠命令	处理命令、集成大模型
bot_installed	机器人被添加到账户	初始化机器人状态
interactive_message_actions	点击按钮	处理按钮操作
chat_message.submit	提交表单	处理表单数据
app_deauthorized	机器人被移除	清理资源

参见：Webhook 事件参考

消息卡片组件

使用以下组件构建丰富的交互式消息：

组件	说明
header	标题和副标题
message	纯文本
fields	键值对
actions	按钮（Primary、Danger、Default 样式）
section	带颜色的侧边栏分组
attachments	带链接的图片
divider	水平分隔线
form_field	文本输入框
dropdown	下拉菜单
date_picker	日期选择器

参见：消息卡片参考，查看完整的组件目录

架构模式

聊天机器人生命周期

User types /command → Webhook receives bot_notification
                            ↓
                     payload.cmd = "user's input"
                            ↓
                     Process command
                            ↓
                     Send response via sendChatbotMessage()

大模型集成模式

case 'bot_notification': {
  const { toJid, cmd, accountId } = payload;
  
  // 1. Call your LLM
  const llmResponse = await callClaude(cmd);
  
  // 2. Send response back
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: llmResponse }]
  });
}

参见：大模型集成指南

示例应用

示例	说明	链接
Chatbot Quickstart	官方教程（推荐入门）	GitHub
Claude Chatbot	基于 Anthropic Claude 的 AI 聊天机器人	GitHub
Unsplash Chatbot	带数据库的图片搜索	GitHub
ERP Chatbot	带定时提醒的 Oracle ERP	GitHub
Task Manager	完整的 CRUD 应用	GitHub

参见：示例应用指南，了解全部 10 个示例的分析

常见操作

向频道发送消息

// Team Chat API
await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    message: 'Hello!',
    to_channel: 'CHANNEL_ID'
  })
});

处理按钮点击

// Webhook handler
case 'interactive_message_actions': {
  const { actionItem, toJid, accountId } = payload;
  
  if (actionItem.value === 'approve') {
    await sendChatbotMessage(toJid, accountId, {
      body: [{ type: 'message', text: '✅ Approved!' }]
    });
  }
}

验证 Webhook 签名

function verifyWebhook(req) {
  const message = `v0:${req.headers['x-zm-request-timestamp']}:${JSON.stringify(req.body)}`;
  const hash = crypto.createHmac('sha256', process.env.ZOOM_VERIFICATION_TOKEN)
    .update(message)
    .digest('hex');
  return req.headers['x-zm-signature'] === `v0=${hash}`;
}

部署

使用 ngrok 进行本地开发

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 4000

# Use HTTPS URL as Bot Endpoint URL in Zoom Marketplace
# Example: https://abc123.ngrok.io/webhook

生产环境部署

参见：部署指南，内容包括：

• Nginx 反向代理设置
• 基础路径配置
• OAuth 重定向 URI 设置

限制

限制项	值
消息长度	4,096 个字符
文件大小	512 MB
每个频道的成员数	10,000
每个用户的频道数	500

安全最佳实践

1. 验证 Webhook 签名 - 始终使用 x-zm-signature 请求头进行校验
2. 清理消息内容 - 限制为 4096 个字符，并移除控制字符
3. 校验 JID - 检查格式：user@domain 或 channel@domain
4. 使用环境变量 - 切勿硬编码凭据
5. 使用 HTTPS - 生产环境 Webhook 必须使用

参见：安全最佳实践

完整文档库

核心概念（从这里开始！）

• API 选择指南 - 在 Team Chat API 与 Chatbot API 之间做出选择
• 环境设置 - 完整的凭据指南
• 认证流程 - OAuth 与 Client Credentials 对比
• Webhook 架构 - Webhook 的工作原理
• 消息卡片结构 - 卡片组件层级

完整示例

• OAuth 设置 - 完整的 OAuth 实现
• 发送消息 - Team Chat API 消息发送
• Chatbot 设置 - 带 Webhook 的完整聊天机器人
• 按钮操作 - 处理交互式按钮
• 表单提交 - 处理表单数据
• 斜杠命令 - 创建自定义命令
• LLM 集成 - Claude/GPT 集成
• 定时提醒 - Cron + 传入 Webhook
• 频道管理 - 创建与管理频道

参考资料

• API 参考 - 所有端点与方法
• Webhook 事件 - 完整的事件参考
• 消息卡片 - 所有卡片组件
• 示例应用 - 10 个官方示例的分析
• 错误代码 - 错误处理指南

故障排查

• OAuth 问题 - 认证失败
• Webhook 问题 - Webhook 调试
• 常见问题 - 快速诊断

资源

• 官方文档：https://developers.zoom.us/docs/team-chat/
• API 参考：https://developers.zoom.us/docs/api/rest/reference/chatbot/
• 开发者论坛：https://devforum.zoom.us/
• 应用市场：https://marketplace.zoom.us/

---

需要帮助？ 请从下方的综合索引部分开始，获取完整导航。

---

综合索引

本节内容迁移自 SKILL.md。

Zoom Team Chat 技能的完整导航指南。

快速入门路径

• 从这里开始：快速开始
• 优先快速排障：5 分钟运行手册

路径 1：Team Chat API（用户级消息）

用于以用户账户身份发送消息。

1. API 选择指南 - 确认 Team Chat API 是否适合
2. 环境配置 - 获取凭证
3. OAuth 配置示例 - 实现身份验证
4. 发送消息示例 - 发送第一条消息

路径 2：Chatbot API（交互式机器人）

用于构建带有富消息的交互式聊天机器人。

1. API 选择指南 - 确认 Chatbot API 是否适合
2. 环境配置 - 获取凭证（包括 Bot JID）
3. Webhook 架构 - 了解 Webhook 事件
4. Chatbot 配置示例 - 构建第一个机器人
5. 消息卡片参考 - 创建富消息

核心概念

两种 API 都需要理解的基础内容。

文档	描述
API 选择指南	选择 Team Chat API 还是 Chatbot API
环境配置	完整的凭证与应用配置
身份验证流程	OAuth 与 Client Credentials 对比
Webhook 架构	Webhook 的工作原理（Chatbot API）
消息卡片结构	卡片组件层级
部署指南	生产环境部署策略
安全最佳实践	保障集成安全

完整示例

常见场景的可运行代码。

身份验证

示例	描述
OAuth 配置	用户 OAuth 流程实现
Token 管理	刷新 Token、过期处理

基础操作

示例	描述
发送消息	Team Chat API 消息发送
Chatbot 配置	带 Webhook 的完整聊天机器人
列出频道	获取用户的频道
创建频道	创建公开/私有频道

交互功能（Chatbot API）

示例	描述
按钮操作	处理按钮点击
表单提交	处理表单数据
斜杠命令	创建自定义命令
下拉选择	频道/成员选择器

高级集成

示例	描述
大模型集成	集成 Claude/GPT
定时提醒	Cron + 传入式 Webhook
数据库集成	存储会话状态
多步工作流	复杂的用户交互

参考资料

API 文档

参考	描述
API 参考	指引与常用端点
Webhook 事件	事件类型与处理清单
消息卡片	所有卡片组件
错误码	错误处理指南

示例应用

参考	描述
示例应用	示例应用索引与说明

Field Guides

Reference	Description
JID Formats	了解 JID 标识符
Scopes Reference	常用 scopes
Rate Limits	限流指南

Troubleshooting

Guide	Description
Common Issues	快速诊断与解决方案
OAuth Issues	认证失败
Webhook Issues	Webhook 调试
Message Issues	消息发送问题
Deployment Issues	生产环境问题

Architecture Patterns

Chatbot Lifecycle

User Action → Webhook → Process → Response

LLM Integration Pattern

User Input → Chatbot receives → Call LLM → Send response

Approval Workflow Pattern

Request → Send card with buttons → User clicks → Update status → Notify

Common Use Cases

Notifications

• CI/CD 构建通知
• 服务器监控告警
• 定时报告
• 系统健康检查

Workflows

• 审批请求
• 任务分配
• 状态更新
• 表单提交

Integrations

• 基于大模型的助手
• 数据库查询
• 外部 API 集成
• 文件/图片分享

Automation

• 定时消息
• 自动回复
• 数据收集
• 报告生成

Resource Links

Official Documentation

• Team Chat Docs - 官方概览
• Chatbot Docs - Chatbot 指南
• API Reference - REST API 文档
• App Marketplace - 创建和管理应用

Sample Code

• Chatbot Quickstart - 官方教程
• Claude Chatbot - AI 集成
• Unsplash Chatbot - 图片搜索机器人
• ERP Chatbot - 企业集成
• Task Manager - 完整的 CRUD 应用

Tools

• App Card Builder - 可视化卡片设计器
• ngrok - 本地 Webhook 测试
• Postman - API 测试

Community

• Developer Forum - 提问交流
• GitHub Discussions - 社区支持
• Developer Support - 官方支持

Documentation Status

✅ Complete

• 主入口 skill.md
• API 选择指南
• 环境搭建
• Webhook 架构
• Chatbot 搭建示例（完整可运行代码）
• Message Cards 参考
• 常见问题排查

📝 Pending (High Priority)

• OAuth 设置示例
• 发送消息示例
• 按钮操作示例
• 大模型集成示例
• Webhook 事件参考
• API 参考
• 示例应用分析

📋 Planned (Lower Priority)

• 表单提交示例
• 频道管理示例
• 数据库集成示例
• 错误码参考
• 限流指南
• 部署问题排查

Getting Started Checklist

For Team Chat API

• 阅读 API Selection Guide
• 完成 Environment Setup
• 获取 Client ID、Client Secret
• 添加所需 scopes
• 实现 OAuth 流程
• 发送第一条消息

For Chatbot API

• 阅读 API Selection Guide
• 完成 Environment Setup
• 获取 Client ID、Client Secret、Bot JID、Secret Token、Account ID
• 在 Features 中启用 Team Chat
• 配置 Bot Endpoint URL 和 Slash Command
• 设置 ngrok 进行本地测试
• 实现 Webhook 处理程序
• 发送第一条 Chatbot 消息

版本历史

• v1.0（2026-02-09）- 初始完整文档
  • 核心概念（API 选择、环境配置、Webhook）
  • 完整的聊天机器人配置示例
  • 消息卡片参考
  • 常见问题排查

支持

请将本 SKILL.md 作为导航入口，查阅 Team Chat API 的选择、配置、示例和故障排查内容。

环境变量

• 标准化 .env 键名及各项取值的查找位置，请参阅 references/environment-variables.md。