/team-chat

name: build-zoom-team-chat-app
description: "Reference skill for Zoom Team Chat. Use after routing to a chat workflow when building user-scoped messaging integrations, chatbot experiences, rich cards, buttons, slash commands, or chat webhooks."
triggers:
  - "zoom team chat"
  - "zoom chatbot"
  - "zoom messaging"
  - "team chat api"
  - "chatbot api"
  - "zoom slash commands"
  - "zoom chat integration"

/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:

// 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](examples/send-message.md)

Quick Start: Chatbot API

Build an interactive chatbot:

// 1. Get chatbot token (client_credentials)
async function getChatbotToken() {
  const credentials = Buffer.from(
    `${CLIENT_ID}:${CLIENT_SECRET}`