Build Zoom Team Chat App

API Selection Guide

Zoom Team Chat offers two distinct APIs for different use cases. Choose the right one before you start building.

Critical First Decision

Pick one of these integration types before writing code:

• User type -> Team Chat API -> User OAuth -> /v2/chat/users/...

• Bot type -> Chatbot API -> Client Credentials -> /v2/im/chat/messages

Most implementation issues come from mixing user-type auth with bot-type endpoints (or the opposite).

Quick Decision Matrix

Team Chat API (User-Level Messaging)

What It Is

The Team Chat API allows your application to send messages as an authenticated user. Messages appear in Team Chat as if the user sent them manually.

When to Use

✅ Use Team Chat API when:

• You want to send simple text messages programmatically

• Messages should appear as sent by a specific user

• You're building CI/CD notifications

• You're automating user-level messaging

• You don't need interactive components (buttons, forms)

Key Characteristics

Example Use Cases

1. CI/CD Notifications

   Copy

   User: "Build #123 completed successfully"

2. Automated Reporting

   Copy

   User: "Daily sales report: $10,000"

3. Task Reminders

   Copy

   User: "Reminder: Team meeting in 15 minutes"

Chatbot API (Bot-Level Interactions)

What It Is

The Chatbot API allows your application to send messages as a bot. Bots can send rich, interactive messages with buttons, forms, images, and handle user interactions via webhooks.

When to Use

✅ Use Chatbot API when:

• You want to build an interactive chatbot

• You need rich message formatting (cards, buttons, forms)

• You want to handle slash commands (e.g., /weather)

• You need to respond to button clicks or form submissions

• You're integrating LLMs or AI provider APIs

• You want scheduled notifications

Key Characteristics

Example Use Cases

1. Support Bot

   Copy

   Bot: "How can I help you?"
   [Help Center] [Contact Support] [Report Bug]

2. Approval Workflow

   Copy

   Bot: "Expense Report: $500"
   Branch: main
   Requester: John
   [Approve] [Reject]

3. AI Assistant

   Copy

   User: "/ask What's the weather?"
   Bot: "The weather in San Francisco is 72°F and sunny."

Feature Comparison

Authentication Comparison

Team Chat API (User OAuth)

Flow: authorization_code Requires: User login and consent Token Scope: User's data only

// Step 1: Redirect user to OAuth consent page
const authUrl = `https://zoom.us/oauth/authorize?response_type=code&client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}`;

// Step 2: Exchange auth code for access token
const tokens = await exchangeCodeForToken(code);

// Step 3: Use access token to send messages
fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  headers: { 'Authorization': `Bearer ${tokens.access_token}` }
});

Chatbot API (Client Credentials)

Flow: client_credentials Requires: No user login Token Scope: Bot actions only

// Step 1: Get bot token (no user interaction)
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}` },
  body: 'grant_type=client_credentials'
});

const { access_token } = await response.json();

// Step 2: Use access token to send bot messages
fetch('https://api.zoom.us/v2/im/chat/messages', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});

Can I Use Both?

Yes! You can use both APIs in the same application.

Example: Task management app

• Team Chat API: User creates a task → message appears as "User created task #123"

• Chatbot API: Bot sends reminders → "Task #123 is due today [View] [Snooze]"

Decision Tree

Need rich interactive messages?
├─ Yes → Chatbot API
└─ No
   └─ Need webhooks (slash commands, button clicks)?
      ├─ Yes → Chatbot API
      └─ No
         └─ Messages should appear as user?
            ├─ Yes → Team Chat API
            └─ No → Chatbot API

Common Misconceptions

❌ "I need to use Server-to-Server OAuth for bots"

Reality: Chatbots require General App (OAuth), not Server-to-Server OAuth. S2S apps don't support the Chatbot feature.

❌ "Team Chat API can send buttons"

Reality: Only Chatbot API supports interactive components (buttons, forms, dropdowns).

❌ "Chatbot API requires user login"

Reality: Chatbot API uses client_credentials flow (no user login needed).

❌ "OAuth token endpoint is /oauth/token"

Reality: Use https://zoom.us/oauth/token for token exchange. Keep https://zoom.us/oauth/authorize for the user consent step.

❌ "I can only use one API per app"

Reality: You can use both APIs in the same application.

Next Steps

If you chose Team Chat API:

1. Environment Setup - Get credentials

2. OAuth Setup - Implement OAuth flow

3. Send Message - Send your first message

If you chose Chatbot API:

1. Environment Setup - Get credentials (including Bot JID)

2. Chatbot Setup - Build your first bot

3. Webhook Architecture - Understand webhook events

Resources

• Official Team Chat API Docs

• Official Chatbot API Docs

• Chatbot Quickstart Sample