build-zoom-team-chat-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/build-zoom-team-chat-app

Background reference for Zoom Team Chat integrations. Use this after the workflow is clear, especially when the Team Chat API versus Chatbot API distinction matters.

Zoom Team Chat集成的背景参考文档。当工作流明确后，尤其是在需要区分Team Chat API和Chatbot API时使用。

Read This First (Critical)

首先阅读（至关重要）

There are two different integration types and they are not interchangeable:

Team Chat API (user type)
- Sends messages as a real authenticated user
- Uses User OAuth (
```
authorization_code
```
  )
- Endpoint family:
```
/v2/chat/users/...
```
Chatbot API (bot type)
- Sends messages as your bot identity
- Uses Client Credentials (
```
client_credentials
```
  )
- Endpoint family:
```
/v2/im/chat/messages
```

If you choose the wrong type early, auth/scopes/endpoints all mismatch and implementation fails.

Official Documentation: https://developers.zoom.us/docs/team-chat/
Chatbot Documentation: https://developers.zoom.us/docs/team-chat/chatbot/extend/
API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/

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

Team Chat API（用户类型）
- 以真实已认证用户身份发送消息
- 使用User OAuth（
```
authorization_code
```
  ）
- 端点系列：
```
/v2/chat/users/...
```
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/

Quick Links

快速链接

New to Team Chat? Follow this path:

Get Started - End-to-end fast path (user type vs bot type)
Choose Your API - Team Chat API vs Chatbot API
Environment Setup - Credentials, scopes, app configuration
OAuth Setup - Complete authentication flow
Send First Message - Working code to send messages

Reference:

Chatbot Message Cards - Complete card component reference
Webhook Events - All webhook event types
API Reference - Endpoints, methods, parameters
Sample Applications - 10+ official sample apps
Integrated Index - see the section below in this file

Having issues?

Authentication errors → OAuth Troubleshooting
Webhook not receiving events → Webhook Setup Guide
Messages not sending → Common Issues
Start with quick checks → 5-Minute Runbook

OAuth endpoint sanity check:

Authorize URL:
```
https://zoom.us/oauth/authorize
```
Token URL:
```
https://zoom.us/oauth/token
```
If
```
/oauth/token
```
returns 404/HTML, use
```
https://zoom.us/oauth/token
```
.

Building Interactive Bots?

Button Actions - Handle button clicks
Form Submissions - Process form data
Slash Commands - Create custom commands

首次接触Team Chat？请遵循以下路径：

快速入门 - 端到端快速流程（用户类型vs机器人类型）
选择API - Team Chat API vs Chatbot API
环境配置 - 凭证、权限范围、应用配置
OAuth配置 - 完整认证流程
发送第一条消息 - 可运行的消息发送代码

参考资料：

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
```
。

构建交互式机器人？

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

Quick Decision: Which API?

快速决策：选择哪个API？

Use Case	API to Use
Send notifications from scripts/CI/CD	Team Chat API
Automate messages as a user	Team Chat API
Build an interactive chatbot	Chatbot API
Respond to slash commands	Chatbot API
Create messages with buttons/forms	Chatbot API
Handle user interactions	Chatbot API

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

Team Chat API (User-Level)

Team Chat API（用户级）

Messages appear as sent by authenticated user
Requires User OAuth (authorization_code flow)

Endpoint:

POST https://api.zoom.us/v2/chat/users/me/messages

Scopes:
```
chat_message:write
```
,
```
chat_channel:read
```

消息显示为由已认证用户发送
需要User OAuth（authorization_code流程）

端点：

POST https://api.zoom.us/v2/chat/users/me/messages

权限范围：
```
chat_message:write
```
,
```
chat_channel:read
```

Chatbot API (Bot-Level)

Chatbot API（机器人级）

Messages appear as sent by your bot
Requires Client Credentials grant

Endpoint:

POST https://api.zoom.us/v2/im/chat/messages

Scopes:
```
imchat:bot
```
(auto-added)
Rich cards: buttons, forms, dropdowns, images

消息显示为由你的机器人发送
需要Client Credentials授权

端点：

POST https://api.zoom.us/v2/im/chat/messages

权限范围：
```
imchat:bot
```
（自动添加）
富卡片：按钮、表单、下拉菜单、图片

Prerequisites

前提条件

System Requirements

系统要求

Zoom account
Account owner, admin, or Zoom for developers role enabled
- To enable: User Management → Roles → Role Settings → Advanced features → Enable Zoom for developers

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

Create Zoom App

创建Zoom应用

Go to Zoom App Marketplace
Click Develop → Build App
Select General App (OAuth)

⚠️ Do NOT use Server-to-Server OAuth - S2S apps don't have the Chatbot/Team Chat feature. Only General App (OAuth) supports chatbots.

访问Zoom应用市场
点击Develop → Build App
选择General App（OAuth）

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

Required Credentials

所需凭证

From Zoom Marketplace → Your App:

Credential	Location	Used By
Client ID	App Credentials → Development	Both APIs
Client Secret	App Credentials → Development	Both APIs
Account ID	App Credentials → Development	Chatbot API
Bot JID	Features → Chatbot → Bot Credentials	Chatbot API
Secret Token	Features → Team Chat Subscriptions	Chatbot API

See: Environment Setup Guide for complete configuration steps.

从Zoom应用市场 → 你的应用中获取：

凭证	位置	使用方
Client ID	应用凭证 → 开发环境	两个API均需使用
Client Secret	应用凭证 → 开发环境	两个API均需使用
Account ID	应用凭证 → 开发环境	Chatbot API
Bot JID	功能 → Chatbot → 机器人凭证	Chatbot API
Secret Token	功能 → Team Chat订阅	Chatbot API

查看：环境配置指南获取完整配置步骤。

Quick Start: Team Chat API

快速开始：Team Chat API

Send a message as a user:

javascript

// 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" }

Complete example: Send Message Guide

以用户身份发送消息：

javascript

// 1. 通过OAuth获取访问令牌
const accessToken = await getOAuthToken(); // 查看examples/oauth-setup.md

// 2. 向频道发送消息
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" }

完整示例：发送消息指南

Quick Start: Chatbot API

快速开始：Chatbot API

Build an interactive chatbot:

javascript

// 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' }
          ]
        }
      ]
    }
  })
});

Complete example: Chatbot Setup Guide

构建交互式聊天机器人：

javascript

// 1. 获取聊天机器人令牌（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. 发送带按钮的聊天机器人消息
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,           // 来自Webhook
    account_id: payload.accountId,   // 来自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' }
          ]
        }
      ]
    }
  })
});

完整示例：Chatbot配置指南

Key Features

核心功能

Team Chat API

Feature	Description
Send Messages	Post messages to channels or direct messages
List Channels	Get user's channels with metadata
Create Channels	Create public/private channels programmatically
Threaded Replies	Reply to specific messages in threads
Edit/Delete	Modify or remove messages

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

Chatbot API

Feature	Description
Rich Message Cards	Headers, images, fields, buttons, forms
Slash Commands	Custom `/commands` trigger webhooks
Button Actions	Interactive buttons with webhook callbacks
Form Submissions	Collect user input with forms
Dropdown Selects	Channel, member, date/time pickers
LLM Integration	Easy integration with Claude, GPT, etc.

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

Webhook Events (Chatbot API)

Webhook事件（Chatbot API）

Event	Trigger	Use Case
`bot_notification`	User messages bot or uses slash command	Process commands, integrate LLM
`bot_installed`	Bot added to account	Initialize bot state
`interactive_message_actions`	Button clicked	Handle button actions
`chat_message.submit`	Form submitted	Process form data
`app_deauthorized`	Bot removed	Cleanup

See: Webhook Events Reference

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

查看：Webhook事件参考

Message Card Components

消息卡片组件

Build rich interactive messages with these components:

Component	Description
header	Title and subtitle
message	Plain text
fields	Key-value pairs
actions	Buttons (Primary, Danger, Default styles)
section	Colored sidebar grouping
attachments	Images with links
divider	Horizontal line
form_field	Text input
dropdown	Select menu
date_picker	Date selection

See: Message Cards Reference for complete component catalog

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

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

查看：消息卡片参考获取完整组件目录

Architecture Patterns

架构模式

Chatbot Lifecycle

Chatbot生命周期

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

用户输入/command → Webhook接收bot_notification
                            ↓
                     payload.cmd = "用户输入内容"
                            ↓
                     处理命令
                            ↓
                     通过sendChatbotMessage()发送响应

LLM Integration Pattern

LLM集成模式

javascript

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 }]
  });
}

See: LLM Integration Guide

javascript

case 'bot_notification': {
  const { toJid, cmd, accountId } = payload;
  
  // 1. 调用LLM
  const llmResponse = await callClaude(cmd);
  
  // 2. 发送响应
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: llmResponse }]
  });
}

查看：LLM集成指南

Sample Applications

示例应用

Sample	Description	Link
Chatbot Quickstart	Official tutorial (recommended start)	GitHub
Claude Chatbot	AI chatbot with Anthropic Claude	GitHub
Unsplash Chatbot	Image search with database	GitHub
ERP Chatbot	Oracle ERP with scheduled alerts	GitHub
Task Manager	Full CRUD app	GitHub

See: Sample Applications Guide for analysis of all 10 samples

示例	描述	链接
Chatbot快速入门	官方教程（推荐入门）	GitHub
Claude Chatbot	集成Anthropic Claude的AI聊天机器人	GitHub
Unsplash Chatbot	带数据库的图片搜索机器人	GitHub
ERP Chatbot	带定时提醒的Oracle ERP集成	GitHub
任务管理器	完整CRUD应用	GitHub

查看：示例应用指南获取全部10个示例的分析

Common Operations

常见操作

Send Message to Channel

向频道发送消息

javascript

// 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'
  })
});

javascript

// 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'
  })
});

Handle Button Click

处理按钮点击

javascript

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

javascript

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

Verify Webhook Signature

验证Webhook签名

javascript

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}`;
}

javascript

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}`;
}

Deployment

部署

ngrok for Local Development

使用ngrok进行本地开发

bash

undefined

bash

undefined

Install ngrok

安装ngrok

npm install -g ngrok

Expose local server

暴露本地服务器

ngrok http 4000

Use HTTPS URL as Bot Endpoint URL in Zoom Marketplace

使用HTTPS URL作为Zoom应用市场中的Bot Endpoint URL

Example: https://abc123.ngrok.io/webhook

示例：https://abc123.ngrok.io/webhook

undefined

undefined

Production Deployment

生产环境部署

See: Deployment Guide for:

Nginx reverse proxy setup
Base path configuration
OAuth redirect URI setup

查看：部署指南获取：

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

Limitations

限制

Limit	Value
Message length	4,096 characters
File size	512 MB
Members per channel	10,000
Channels per user	500

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

Security Best Practices

安全最佳实践

Verify webhook signatures - Always validate using
```
x-zm-signature
```
header
Sanitize messages - Limit to 4096 chars, remove control characters
Validate JIDs - Check format:
```
user@domain
```
or
```
channel@domain
```
Environment variables - Never hardcode credentials
Use HTTPS - Required for production webhooks

See: Security Best Practices

验证Webhook签名 - 始终使用
```
x-zm-signature
```
头进行验证
消息 sanitize - 限制为4096字符，移除控制字符
验证JID格式 - 检查格式：
```
user@domain
```
或
```
channel@domain
```
使用环境变量 - 切勿硬编码凭证
使用HTTPS - 生产环境Webhook必须使用HTTPS

查看：安全最佳实践

Complete Documentation Library

完整文档库

Core Concepts (Start Here!)

核心概念（从此处开始！）

API Selection Guide - Choose Team Chat API vs Chatbot API
Environment Setup - Complete credentials guide
Authentication Flows - OAuth vs Client Credentials
Webhook Architecture - How webhooks work
Message Card Structure - Card component hierarchy

API选择指南 - 选择Team Chat API还是Chatbot API
环境配置 - 完整凭证指南
认证流程 - OAuth vs Client Credentials
Webhook架构 - Webhook工作原理
消息卡片结构 - 卡片组件层级

Complete Examples

完整示例

OAuth Setup - Full OAuth implementation
Send Message - Team Chat API message sending
Chatbot Setup - Complete chatbot with webhooks
Button Actions - Handle interactive buttons
Form Submissions - Process form data
Slash Commands - Create custom commands
LLM Integration - Claude/GPT integration
Scheduled Alerts - Cron + incoming webhooks
Channel Management - Create/manage channels

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

References

参考资料

API Reference - All endpoints and methods
Webhook Events - Complete event reference
Message Cards - All card components
Sample Applications - Analysis of 10 official samples
Error Codes - Error handling guide

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

Troubleshooting

故障排查

OAuth Issues - Authentication failures
Webhook Issues - Webhook debugging
Common Issues - Quick diagnostics

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

Resources

资源

Official Docs: https://developers.zoom.us/docs/team-chat/
API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/
Dev Forum: https://devforum.zoom.us/
App Marketplace: https://marketplace.zoom.us/

Need help? Start with Integrated Index section below for complete navigation.

官方文档：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/

需要帮助？ 请查看下方的集成索引章节获取完整导航。

Integrated Index

集成索引

This section was migrated from
SKILL.md
.

Complete navigation guide for the Zoom Team Chat skill.

此章节迁移自
SKILL.md
。

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

Quick Start Paths

快速入门路径

Start here: Get Started
Fast troubleshooting first: 5-Minute Runbook

从此开始：快速入门
快速故障排查：5分钟运行手册

Path 1: Team Chat API (User-Level Messaging)

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

For sending messages as a user account.

API Selection Guide - Confirm Team Chat API is right
Environment Setup - Get credentials
OAuth Setup Example - Implement authentication
Send Message Example - Send your first message

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

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

Path 2: Chatbot API (Interactive Bots)

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

For building interactive chatbots with rich messages.

API Selection Guide - Confirm Chatbot API is right
Environment Setup - Get credentials (including Bot JID)
Webhook Architecture - Understand webhook events
Chatbot Setup Example - Build your first bot
Message Cards Reference - Create rich messages

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

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

Core Concepts

核心概念

Essential understanding for both APIs.

Document	Description
API Selection Guide	Choose Team Chat API vs Chatbot API
Environment Setup	Complete credentials and app configuration
Authentication Flows	OAuth vs Client Credentials
Webhook Architecture	How webhooks work (Chatbot API)
Message Card Structure	Card component hierarchy
Deployment Guide	Production deployment strategies
Security Best Practices	Secure your integration

两种API都需要掌握的基础内容。

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

Complete Examples

完整示例

Working code for common scenarios.

常见场景的可运行代码。

Authentication

认证

Example	Description
OAuth Setup	User OAuth flow implementation
Token Management	Refresh tokens, expiration handling

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

Basic Operations

基础操作

Example	Description
Send Message	Team Chat API message sending
Chatbot Setup	Complete chatbot with webhooks
List Channels	Get user's channels
Create Channel	Create public/private channels

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

Interactive Features (Chatbot API)

交互式功能（Chatbot API）

Example	Description
Button Actions	Handle button clicks
Form Submissions	Process form data
Slash Commands	Create custom commands
Dropdown Selects	Channel/member pickers

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

Advanced Integration

高级集成

Example	Description
LLM Integration	Integrate Claude/GPT
Scheduled Alerts	Cron + incoming webhooks
Database Integration	Store conversation state
Multi-Step Workflows	Complex user interactions

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

References

参考资料

API Documentation

API文档

Reference	Description
API Reference	Pointers and common endpoints
Webhook Events	Event types and handling checklist
Message Cards	All card components
Error Codes	Error handling guide

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

Sample Applications

示例应用

Reference	Description
Sample Applications	Sample app index/notes

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

Field Guides

领域指南

Reference	Description
JID Formats	Understanding JID identifiers
Scopes Reference	Common scopes
Rate Limits	Throttling guidance

参考	描述
JID格式	理解JID标识符
权限范围参考	常用权限范围
速率限制	限流指引

Troubleshooting

故障排查

Guide	Description
Common Issues	Quick diagnostics and solutions
OAuth Issues	Authentication failures
Webhook Issues	Webhook debugging
Message Issues	Message sending problems
Deployment Issues	Production problems

指南	描述
常见问题	快速诊断和解决方案
OAuth问题	认证失败
Webhook问题	Webhook调试
消息问题	消息发送问题
部署问题	生产环境问题

Architecture Patterns

架构模式

Chatbot Lifecycle

Chatbot生命周期

User Action → Webhook → Process → Response

用户操作 → Webhook → 处理 → 响应

LLM Integration Pattern

LLM集成模式

User Input → Chatbot receives → Call LLM → Send response

用户输入 → Chatbot接收 → 调用LLM → 发送响应

Approval Workflow Pattern

审批工作流模式

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

请求 → 发送带按钮的卡片 → 用户点击 → 更新状态 → 通知

Common Use Cases

常见使用场景

Notifications

通知

CI/CD build notifications
Server monitoring alerts
Scheduled reports
System health checks

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

Workflows

工作流

Approval requests
Task assignment
Status updates
Form submissions

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

Integrations

集成

LLM-powered assistants
Database queries
External API integration
File/image sharing

LLM驱动助手
数据库查询
外部API集成
文件/图片分享

Automation

自动化

Scheduled messages
Auto-responses
Data collection
Report generation

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

Resource Links

资源链接

Official Documentation

官方文档

Team Chat Docs - Official overview
Chatbot Docs - Chatbot guide
API Reference - REST API docs
App Marketplace - Create and manage apps

Team Chat文档 - 官方概述
Chatbot文档 - Chatbot指南
API参考 - REST API文档
应用市场 - 创建和管理应用

Sample Code

示例代码

Chatbot Quickstart - Official tutorial
Claude Chatbot - AI integration
Unsplash Chatbot - Image search bot
ERP Chatbot - Enterprise integration
Task Manager - Full CRUD app

Chatbot快速入门 - 官方教程
Claude Chatbot - AI集成
Unsplash Chatbot - 图片搜索机器人
ERP Chatbot - 企业集成
任务管理器 - 完整CRUD应用

Tools

工具

App Card Builder - Visual card designer
ngrok - Local webhook testing
Postman - API testing

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

Community

社区

Developer Forum - Ask questions
GitHub Discussions - Community support
Developer Support - Official support

开发者论坛 - 提问交流
GitHub讨论区 - 社区支持
开发者支持 - 官方支持

Documentation Status

文档状态

✅ Complete

✅ 已完成

Main skill.md entry point
API Selection Guide
Environment Setup
Webhook Architecture
Chatbot Setup Example (complete working code)
Message Cards Reference
Common Issues Troubleshooting

主skill.md入口
API选择指南
环境配置
Webhook架构
Chatbot配置示例（完整可运行代码）
消息卡片参考
常见问题故障排查

📝 Pending (High Priority)

📝 待完成（高优先级）

OAuth Setup Example
Send Message Example
Button Actions Example
LLM Integration Example
Webhook Events Reference
API Reference
Sample Applications Analysis

OAuth配置示例
发送消息示例
按钮操作示例
LLM集成示例
Webhook事件参考
API参考
示例应用分析

📋 Planned (Lower Priority)

📋 计划中（低优先级）

Form Submissions Example
Channel Management Examples
Database Integration Example
Error Codes Reference
Rate Limits Guide
Deployment troubleshooting

表单提交示例
频道管理示例
数据库集成示例
错误码参考
速率限制指南
部署故障排查

Getting Started Checklist

快速入门清单

For Team Chat API

针对Team Chat API

For Chatbot API

针对Chatbot API

Version History

版本历史

v1.0 (2026-02-09) - Initial comprehensive documentation
- Core concepts (API selection, environment setup, webhooks)
- Complete chatbot setup example
- Message cards reference
- Common issues troubleshooting

v1.0（2026-02-09） - 初始综合文档
- 核心概念（API选择、环境配置、Webhook）
- 完整Chatbot配置示例
- 消息卡片参考
- 常见问题故障排查

Support

支持

Use this SKILL.md as the navigation hub for Team Chat API selection, setup, examples, and troubleshooting.

将此SKILL.md作为Team Chat API选择、配置、示例和故障排查的导航中心。

Environment Variables

环境变量

See references/environment-variables.md for standardized
```
.env
```
keys and where to find each value.

查看references/environment-variables.md获取标准化
```
.env
```
键及每个值的获取位置。