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/ (opens in a new tab)
Chatbot Documentation: https://developers.zoom.us/docs/team-chat/chatbot/extend/ (opens in a new tab)
API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/ (opens in a new tab)

Quick Links

New to Team Chat? Follow this path:

1. Get Started (opens in a new tab) - End-to-end fast path (user type vs bot type)
2. Choose Your API (opens in a new tab) - Team Chat API vs Chatbot API
3. Environment Setup (opens in a new tab) - Credentials, scopes, app configuration
4. OAuth Setup (opens in a new tab) - Complete authentication flow
5. Send First Message (opens in a new tab) - Working code to send messages

Reference:

• Chatbot Message Cards (opens in a new tab) - Complete card component reference
• Webhook Events (opens in a new tab) - All webhook event types
• API Reference (opens in a new tab) - Endpoints, methods, parameters
• Sample Applications (opens in a new tab) - 10+ official sample apps
• Integrated Index - see the section below in this file

Having issues?

• Authentication errors → OAuth Troubleshooting (opens in a new tab)
• Webhook not receiving events → Webhook Setup Guide (opens in a new tab)
• Messages not sending → Common Issues (opens in a new tab)
• Start with quick checks → 5-Minute Runbook (opens in a new tab)

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 (opens in a new tab) - Handle button clicks
• Form Submissions (opens in a new tab) - Process form data
• Slash Commands (opens in a new tab) - Create custom commands

Quick Decision: Which 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 (opens in a new tab)
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:

See: Environment Setup Guide (opens in a new tab) 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 (opens in a new tab)

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}`
  ).toString('base64');
  
  const response = await fetch('https://zoom.us/oauth/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });
  
  return (await response.json()).access_token;
}

// 2. Send chatbot message with buttons
const response = await fetch('https://api.zoom.us/v2/im/chat/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    robot_jid: process.env.ZOOM_BOT_JID,
    to_jid: payload.toJid,           // From webhook
    account_id: payload.accountId,   // From webhook
    content: {
      head: {
        text: 'Build Notification',
        sub_head: { text: 'CI/CD Pipeline' }
      },
      body: [
        { type: 'message', text: 'Deployment successful!' },
        {
          type: 'fields',
          items: [
            { key: 'Branch', value: 'main' },
            { key: 'Commit', value: 'abc123' }
          ]
        },
        {
          type: 'actions',
          items: [
            { text: 'View Logs', value: 'view_logs', style: 'Primary' },
            { text: 'Dismiss', value: 'dismiss', style: 'Default' }
          ]
        }
      ]
    }
  })
});

Complete example: Chatbot Setup Guide (opens in a new tab)

Key Features

Team Chat API

Chatbot API

Webhook Events (Chatbot API)

See: Webhook Events Reference (opens in a new tab)

Message Card Components

Build rich interactive messages with these components:

See: Message Cards Reference (opens in a new tab) for complete component catalog

Architecture Patterns

Chatbot Lifecycle

User types /command → Webhook receives bot_notification
                            ↓
                     payload.cmd = "user's input"
                            ↓
                     Process command
                            ↓
                     Send response via sendChatbotMessage()

LLM Integration Pattern

case 'bot_notification': {
  const { toJid, cmd, accountId } = payload;
  
  // 1. Call your LLM
  const llmResponse = await callClaude(cmd);
  
  // 2. Send response back
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: llmResponse }]
  });
}

See: LLM Integration Guide (opens in a new tab)

Sample Applications

See: Sample Applications Guide (opens in a new tab) for analysis of all 10 samples

Common Operations

Send Message to Channel

// Team Chat API
await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    message: 'Hello!',
    to_channel: 'CHANNEL_ID'
  })
});

Handle Button Click

// Webhook handler
case 'interactive_message_actions': {
  const { actionItem, toJid, accountId } = payload;
  
  if (actionItem.value === 'approve') {
    await sendChatbotMessage(toJid, accountId, {
      body: [{ type: 'message', text: '✅ Approved!' }]
    });
  }
}

Verify Webhook Signature

function verifyWebhook(req) {
  const message = `v0:${req.headers['x-zm-request-timestamp']}:${JSON.stringify(req.body)}`;
  const hash = crypto.createHmac('sha256', process.env.ZOOM_VERIFICATION_TOKEN)
    .update(message)
    .digest('hex');
  return req.headers['x-zm-signature'] === `v0=${hash}`;
}

Deployment

ngrok for Local Development

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 4000

# Use HTTPS URL as Bot Endpoint URL in Zoom Marketplace
# Example: https://abc123.ngrok.io/webhook

Production Deployment

See: Deployment Guide (opens in a new tab) for:

• Nginx reverse proxy setup
• Base path configuration
• OAuth redirect URI setup

Limitations

Security Best Practices

1. Verify webhook signatures - Always validate using x-zm-signature header
2. Sanitize messages - Limit to 4096 chars, remove control characters
3. Validate JIDs - Check format: user@domain or channel@domain
4. Environment variables - Never hardcode credentials
5. Use HTTPS - Required for production webhooks

See: Security Best Practices (opens in a new tab)

Complete Documentation Library

Core Concepts (Start Here!)

• API Selection Guide (opens in a new tab) - Choose Team Chat API vs Chatbot API
• Environment Setup (opens in a new tab) - Complete credentials guide
• Authentication Flows (opens in a new tab) - OAuth vs Client Credentials
• Webhook Architecture (opens in a new tab) - How webhooks work
• Message Card Structure (opens in a new tab) - Card component hierarchy

Complete Examples

• OAuth Setup (opens in a new tab) - Full OAuth implementation
• Send Message (opens in a new tab) - Team Chat API message sending
• Chatbot Setup (opens in a new tab) - Complete chatbot with webhooks
• Button Actions (opens in a new tab) - Handle interactive buttons
• Form Submissions (opens in a new tab) - Process form data
• Slash Commands (opens in a new tab) - Create custom commands
• LLM Integration (opens in a new tab) - Claude/GPT integration
• Scheduled Alerts (opens in a new tab) - Cron + incoming webhooks
• Channel Management (opens in a new tab) - Create/manage channels

References

• API Reference (opens in a new tab) - All endpoints and methods
• Webhook Events (opens in a new tab) - Complete event reference
• Message Cards (opens in a new tab) - All card components
• Sample Applications (opens in a new tab) - Analysis of 10 official samples
• Error Codes (opens in a new tab) - Error handling guide

Troubleshooting

• OAuth Issues (opens in a new tab) - Authentication failures
• Webhook Issues (opens in a new tab) - Webhook debugging
• Common Issues (opens in a new tab) - Quick diagnostics

Resources

• Official Docs: https://developers.zoom.us/docs/team-chat/ (opens in a new tab)
• API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/ (opens in a new tab)
• Dev Forum: https://devforum.zoom.us/ (opens in a new tab)
• App Marketplace: https://marketplace.zoom.us/ (opens in a new tab)

Need help? Start with Integrated Index section below for complete navigation.

Integrated Index

This section was migrated from SKILL.md.

Complete navigation guide for the Zoom Team Chat skill.

Quick Start Paths

• Start here: Get Started (opens in a new tab)
• Fast troubleshooting first: 5-Minute Runbook (opens in a new tab)

Path 1: Team Chat API (User-Level Messaging)

For sending messages as a user account.

1. API Selection Guide (opens in a new tab) - Confirm Team Chat API is right
2. Environment Setup (opens in a new tab) - Get credentials
3. OAuth Setup Example (opens in a new tab) - Implement authentication
4. Send Message Example (opens in a new tab) - Send your first message

Path 2: Chatbot API (Interactive Bots)

For building interactive chatbots with rich messages.

1. API Selection Guide (opens in a new tab) - Confirm Chatbot API is right
2. Environment Setup (opens in a new tab) - Get credentials (including Bot JID)
3. Webhook Architecture (opens in a new tab) - Understand webhook events
4. Chatbot Setup Example (opens in a new tab) - Build your first bot
5. Message Cards Reference (opens in a new tab) - Create rich messages

Core Concepts

Essential understanding for both APIs.

Complete Examples

Working code for common scenarios.

Authentication

Basic Operations

Interactive Features (Chatbot API)

Advanced Integration

References

API Documentation

Sample Applications

Field Guides

Troubleshooting

Architecture Patterns

Chatbot Lifecycle

User Action → Webhook → Process → Response

LLM Integration Pattern

User Input → Chatbot receives → Call LLM → Send response

Approval Workflow Pattern

Request → Send card with buttons → User clicks → Update status → Notify

Common Use Cases

Notifications

• CI/CD build notifications
• Server monitoring alerts
• Scheduled reports
• System health checks

Workflows

• Approval requests
• Task assignment
• Status updates
• Form submissions

Integrations

• LLM-powered assistants
• Database queries
• External API integration
• File/image sharing

Automation

• Scheduled messages
• Auto-responses
• Data collection
• Report generation

Resource Links

Official Documentation

• Team Chat Docs (opens in a new tab) - Official overview
• Chatbot Docs (opens in a new tab) - Chatbot guide
• API Reference (opens in a new tab) - REST API docs
• App Marketplace (opens in a new tab) - Create and manage apps

Sample Code

• Chatbot Quickstart (opens in a new tab) - Official tutorial
• Claude Chatbot (opens in a new tab) - AI integration
• Unsplash Chatbot (opens in a new tab) - Image search bot
• ERP Chatbot (opens in a new tab) - Enterprise integration
• Task Manager (opens in a new tab) - Full CRUD app

Tools

• App Card Builder (opens in a new tab) - Visual card designer
• ngrok (opens in a new tab) - Local webhook testing
• Postman (opens in a new tab) - API testing

Community

• Developer Forum (opens in a new tab) - Ask questions
• GitHub Discussions (opens in a new tab) - Community support
• Developer Support (opens in a new tab) - Official support

Documentation Status

✅ Complete

• Main skill.md entry point
• API Selection Guide
• Environment Setup
• Webhook Architecture
• Chatbot Setup Example (complete working code)
• Message Cards Reference
• Common Issues Troubleshooting

📝 Pending (High Priority)

• OAuth Setup Example
• Send Message Example
• Button Actions Example
• LLM Integration Example
• Webhook Events Reference
• API Reference
• Sample Applications Analysis

📋 Planned (Lower Priority)

• Form Submissions Example
• Channel Management Examples
• Database Integration Example
• Error Codes Reference
• Rate Limits Guide
• Deployment troubleshooting

Getting Started Checklist

For Team Chat API

• Not done: Read API Selection Guide (opens in a new tab)
• Not done: Complete Environment Setup (opens in a new tab)
• Not done: Obtain Client ID, Client Secret
• Not done: Add required scopes
• Not done: Implement OAuth flow
• Not done: Send first message

For Chatbot API

• Not done: Read API Selection Guide (opens in a new tab)
• Not done: Complete Environment Setup (opens in a new tab)
• Not done: Obtain Client ID, Client Secret, Bot JID, Secret Token, Account ID
• Not done: Enable Team Chat in Features
• Not done: Configure Bot Endpoint URL and Slash Command
• Not done: Set up ngrok for local testing
• Not done: Implement webhook handler
• Not done: Send first chatbot message

Version History

• v1.0 (2026-02-09) - Initial comprehensive documentation
  • Core concepts (API selection, environment setup, webhooks)
  • Complete chatbot setup example
  • Message cards reference
  • Common issues troubleshooting

Support

Use this SKILL.md as the navigation hub for Team Chat API selection, setup, examples, and troubleshooting.

Environment Variables

• See references/environment-variables.md (opens in a new tab) for standardized .env keys and where to find each value.