/build-zoom-team-chat-app

Read This First (Critical)

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

Quick Links

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

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

• Authentication errors → OAuth Troubleshooting
• Webhook not receiving events → Webhook Setup Guide
• Messages not sending → Common Issues
• Start with quick checks → 5-Minute Runbook

• 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

  .

• Button Actions - Handle button clicks
• Form Submissions - Process form data
• Slash Commands - 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
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

Quick Start: Team Chat API

// 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" }

Quick Start: Chatbot API

// 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' }
          ]
        }
      ]
    }
  })
});

Key Features

Team Chat API

Chatbot API

/commands

Webhook Events (Chatbot API)

bot_notification

bot_installed

interactive_message_actions

chat_message.submit

app_deauthorized

Message Card Components

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 }]
  });
}

Sample Applications

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

• 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

Complete Documentation Library

Core Concepts (Start Here!)

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

Complete Examples

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

References

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

Troubleshooting

• OAuth Issues - Authentication failures
• Webhook Issues - Webhook debugging
• Common Issues - Quick diagnostics

Resources

• Official Docs: https://developers.zoom.us/docs/team-chat/
• API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/
• Dev Forum: https://devforum.zoom.us/
• App Marketplace: https://marketplace.zoom.us/

Integrated Index

SKILL.md

Quick Start Paths

• Start here: Get Started
• Fast troubleshooting first: 5-Minute Runbook

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

1. API Selection Guide - Confirm Team Chat API is right
2. Environment Setup - Get credentials
3. OAuth Setup Example - Implement authentication
4. Send Message Example - Send your first message

Path 2: Chatbot API (Interactive Bots)

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

Core Concepts

Complete Examples

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 - Official overview
• Chatbot Docs - Chatbot guide
• API Reference - REST API docs
• App Marketplace - Create and manage apps

Sample Code

• Chatbot Quickstart - Official tutorial
• Claude Chatbot - AI integration
• Unsplash Chatbot - Image search bot
• ERP Chatbot - Enterprise integration
• Task Manager - Full CRUD app

Tools

• App Card Builder - Visual card designer
• ngrok - Local webhook testing
• Postman - API testing

Community

• Developer Forum - Ask questions
• GitHub Discussions - Community support
• Developer Support - 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

• Read API Selection Guide
• Complete Environment Setup
• Obtain Client ID, Client Secret
• Add required scopes
• Implement OAuth flow
• Send first message

For Chatbot API

• Read API Selection Guide
• Complete Environment Setup
• Obtain Client ID, Client Secret, Bot JID, Secret Token, Account ID
• Enable Team Chat in Features
• Configure Bot Endpoint URL and Slash Command
• Set up ngrok for local testing
• Implement webhook handler
• 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

Environment Variables

• See references/environment-variables.md for standardized

  .env

  keys and where to find each value.