Build Zoom Team Chat App

# /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.

## Read This First (Critical)

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

1. **Team Chat API (user type)** - Sends messages as a real authenticated user - Uses **User OAuth** (`authorization_code`) - Endpoint family: `/v2/chat/users/...`

2. **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/

## Quick Links

**New to Team Chat? Follow this path:**

1. **[Get Started](get-started.md)** - End-to-end fast path (user type vs bot type) 2. **[Choose Your API](concepts/api-selection.md)** - Team Chat API vs Chatbot API 3. **[Environment Setup](concepts/environment-setup.md)** - Credentials, scopes, app configuration 4. **[OAuth Setup](examples/oauth-setup.md)** - Complete authentication flow 5. **[Send First Message](examples/send-message.md)** - Working code to send messages

**Reference:** - **[Chatbot Message Cards](references/message-cards.md)** - Complete card component reference - **[Webhook Events](references/webhook-events.md)** - All webhook event types - **[API Reference](references/api-reference.md)** - Endpoints, methods, parameters - **[Sample Applications](references/samples.md)** - 10+ official sample apps - **Integrated Index** - see the section below in this file

**Having issues?** - Authentication errors → [OAuth Troubleshooting](troubleshooting/oauth-issues.md) - Webhook not receiving events → [Webhook Setup Guide](troubleshooting/webhook-issues.md) - Messages not sending → [Common Issues](troubleshooting/common-issues.md) - Start with quick checks → [5-Minute Runbook](RUNBOOK.md)

**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](examples/button-actions.md) - Handle button clicks - [Form Submissions](examples/form-submissions.md) - Process form data - [Slash Commands](examples/slash-commands.md) - Create custom commands

## Quick Decision: Which 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** |

### Team Chat API (User-Level) - 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`

### Chatbot API (Bot-Level) - 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

## 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**

### Create Zoom App

1. Go to [Zoom App Marketplace](https://marketplace.zoom.us/) 2. Click **Develop** → **Build App** 3. 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.

### 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](concepts/environment-setup.md) for complete configuration steps.

## Quick Start: 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: { 'Authoriz