anthropics--knowledge-work-plugins/partner-built/zoom-plugin/skills/team-chat/concepts/api-selection.md

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

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

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

Aspect	Details
Authentication	User OAuth (authorization_code flow)
Endpoint	POST https://api.zoom.us/v2/chat/users/me/messages
Message Format	Plain text or markdown
Scopes	chat_message:write, chat_channel:read
User Experience	Messages appear from the authenticated user

Example Use Cases

1. CI/CD Notifications

   User: "Build #123 completed successfully"
   

2. Automated Reporting

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

3. Task Reminders

   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 (Claude, GPT, etc.)
• You want scheduled notifications

Key Characteristics

Aspect	Details
Authentication	Client Credentials grant
Endpoint	POST https://api.zoom.us/v2/im/chat/messages
Message Format	Rich cards with components
Scopes	imchat:bot (auto-added)
User Experience	Messages appear from your bot
Interactivity	Buttons, forms, dropdowns, webhooks

Example Use Cases

1. Support Bot

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

2. Approval Workflow

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

3. AI Assistant

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

Feature Comparison

Feature	Team Chat API	Chatbot API
Plain Text Messages	✅	✅
Markdown	✅	✅
Rich Cards	❌	✅
Buttons	❌	✅
Forms	❌	✅
Dropdowns	❌	✅
Images	✅ (basic)	✅ (rich)
Slash Commands	❌	✅
Webhooks	❌	✅
Button Click Handling	❌	✅
Form Submissions	❌	✅

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