Build Zoom Team Chat App

Environment Setup

Complete guide to configuring your Zoom Team Chat development environment, obtaining credentials, and setting up your app.

Prerequisites

• Zoom account

• Account owner, admin, or Zoom for developers role enabled

Enable "Zoom for developers" Role

If you don't have owner/admin privileges:

1. Ask your admin to enable the Zoom for developers role

2. Navigate to: User Management → Roles → Role Settings → Advanced features

3. Enable View and Edit checkboxes for Zoom for developers

Image: Zoom for developers role

Step 1: Create Zoom App

1.1 Access App Marketplace

1. Go to Zoom App Marketplace

2. Click Develop → Build App

1.2 Select App Type

Select: General App (OAuth)

⚠️ CRITICAL: Do NOT select "Server-to-Server OAuth"

Why: Server-to-Server OAuth apps do NOT support the Team Chat/Chatbot features. Only General App (OAuth) supports chatbots and team chat integrations.

Step 2: Basic Information

On the Basic Info page, configure your app:

2.1 App Name

Update the auto-generated app name:

• Click the edit icon (pencil)

• Enter your app name (e.g., "My Team Chat Bot")

• Click outside the field to save

2.2 App Management Type

Choose how your app is managed:

For most chatbots: Choose Admin-managed

Important: App management type affects available features and scopes. If you change it later, reconfirm your selected features and scopes.

2.3 App Credentials (Auto-generated)

The build flow automatically generates:

Note: Development and production credentials are different.

2.4 OAuth Information

OAuth Redirect URL (Required)

Enter your OAuth callback endpoint:

Local development:

http://YOUR_DEV_HOST:4000/auth/callback

Production:

https://yourdomain.com/auth/callback

OAuth Allow Lists (Required)

Add all URLs that Zoom should allow as valid OAuth redirects:

Examples:

• Complete URL: https://subdomain.domain.tld/path/oauth/callback

• Base URL: https://subdomain.domain.tld

Step 3: Enable Team Chat (Chatbot API Only)

Skip this step if you're only using Team Chat API (user-level messaging)

3.1 Navigate to Features Page

Go to Features page → Surface tab

3.2 Select Team Chat Product

In Select where to use your app, check Team Chat

3.3 Configure App URLs

3.4 Enable Team Chat Subscription

Configure webhook settings:

Critical: Your bot will NOT appear in Team Chat unless you enable Team Chat Subscription!

Step 4: Get Credentials

4.1 App Credentials (Both APIs)

Navigate to App Credentials → Development:

4.2 Bot JID (Chatbot API Only)

Note: Bot JID only appears AFTER enabling Chatbot in Features tab

To find Bot JID:

1. Go to Features tab in left sidebar

2. Ensure Chatbot toggle is ON

3. Click Chatbot section to expand

4. Scroll to Bot Credentials section

5. You'll see two JIDs:

   • Bot JID (Development): Use for testing

   • Bot JID (Production): Use for live apps

Format: [email protected]

4.3 Webhook Secret Token (Chatbot API Only)

Navigate to Features → Team Chat Subscriptions → Secret Token

This token is used to verify webhook signatures.

4.4 Credentials Summary

Step 5: Configure Scopes

Navigate to Scopes page in your app.

Team Chat API Scopes

Manually add these scopes:

• chat_message:write - Send messages

• chat_message:read - Read messages

• chat_channel:read - List channels

• chat_channel:write - Create/manage channels

Chatbot API Scopes

When you enable Team Chat Subscription, these scopes are automatically added:

• imchat:bot - Basic chatbot functionality

• team_chat:read:list_user_channels:admin - List channels

• team_chat:read:list_members:admin - List members

Step 6: Create .env File

For Team Chat API (User-Level)

# .env file
ZOOM_CLIENT_ID=your_client_id_here
ZOOM_CLIENT_SECRET=your_client_secret_here
ZOOM_REDIRECT_URI=http://YOUR_DEV_HOST:4000/auth/callback

PORT=4000

For Chatbot API (Bot-Level)

# .env file
ZOOM_CLIENT_ID=your_client_id_here
ZOOM_CLIENT_SECRET=your_client_secret_here
[email protected]
ZOOM_VERIFICATION_TOKEN=your_webhook_secret_token
ZOOM_ACCOUNT_ID=your_account_id

PORT=4000

.env.example Template

Create this file in your project root:

# Zoom App Credentials (Required for both APIs)
ZOOM_CLIENT_ID=
ZOOM_CLIENT_SECRET=
ZOOM_REDIRECT_URI=http://YOUR_DEV_HOST:4000/auth/callback

# Chatbot Credentials (Required for Chatbot API only)
ZOOM_BOT_JID=
ZOOM_VERIFICATION_TOKEN=
ZOOM_ACCOUNT_ID=

# Server Configuration
PORT=4000

Step 7: Test Your App

On the Local Test page:

7.1 Add App to Your Account

1. Click Add App Now

2. Click Allow to authorize the app

3. You'll be redirected to your OAuth redirect URL

7.2 Preview App Listing

Click Preview Your App Listing Page to see how your app appears in the marketplace.

7.3 Share with Team Members

To share your app with other users on your account:

1. Go to Authorization URL section

2. Click Generate

3. Click Copy

4. Share the URL with your team members

Note: Beta apps can only be installed by members of the developer's Zoom account (security restriction).

Common Setup Issues

Verification Checklist

Before proceeding to development, verify:

• [ ] Created General App (OAuth) (not Server-to-Server)

• [ ] Selected appropriate App Management Type

• [ ] Configured OAuth redirect URL

• [ ] Added URLs to OAuth allow lists

• [ ] Enabled Team Chat in Surface tab (for chatbots)

• [ ] Configured Team Chat Subscription (for chatbots)

• [ ] Added all required scopes

• [ ] Obtained all required credentials

• [ ] Created .env file with credentials

• [ ] Successfully added app to your account

Next Steps

For Team Chat API:

1. Authentication Flows - Understand OAuth

2. OAuth Setup Example - Implement OAuth

3. Send Message Example - Send first message

For Chatbot API:

1. Webhook Architecture - Understand webhooks

2. Chatbot Setup Example - Build your bot

3. Message Cards Reference - Create rich messages

Resources

• Zoom App Marketplace

• OAuth Documentation

• Chatbot Documentation

• Using Role Management