build-zoom-team-chat-app

SKILL.md

/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:

Team Chat API (user type)

Sends messages as a real authenticated user

Uses User OAuth (authorization_code)

Endpoint family: /v2/chat/users/...

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/

Chatbot Documentation: https://developers.zoom.us/docs/team-chat/chatbot/extend/

API Reference: https://developers.zoom.us/docs/api/rest/reference/chatbot/

Quick Links

New to Team Chat? Follow this path:

Get Started - End-to-end fast path (user type vs bot type)

Choose Your API - Team Chat API vs Chatbot API

Environment Setup - Credentials, scopes, app configuration

OAuth Setup - Complete authentication flow

Send First Message - Working code to send messages

Reference:

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

Having issues?

Authentication errors → OAuth Troubleshooting

Webhook not receiving events → Webhook Setup Guide

Messages not sending → Common Issues

Start with quick checks → 5-Minute Runbook

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 - Handle button clicks

Form Submissions - Process form data

Slash Commands - Create custom commands

Quick Decision: Which API?

Use Case
API to Use

Send notifications from scripts/CI/CD
Team Chat API

Automate messages as a user
Team Chat API

Build an interactive chatbot
Chatbot API

Respond to slash commands
Chatbot API

Create messages with buttons/forms
Chatbot API

Handle user interactions
Chatbot 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

Go to Zoom App Marketplace

Click Develop → Build App

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:

Credential
Location
Used By

Client ID
App Credentials → Development
Both APIs

Client Secret
App Credentials → Development
Both APIs

Account ID
App Credentials → Development
Chatbot API

Bot JID
Features → Chatbot → Bot Credentials
Chatbot API

Secret Token
Features → Team Chat Subscriptions
Chatbot API

See: Environment Setup Guide 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

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

Key Features

Team Chat API

Feature
Description

Send Messages
Post messages to channels or direct messages

List Channels
Get user's channels with metadata

Create Channels
Create public/private channels programmatically

Threaded Replies
Reply to specific messages in threads

Edit/Delete
Modify or remove messages

Chatbot API

Feature
Description

Rich Message Cards
Headers, images, fields, buttons, forms

Slash Commands
Custom /commands trigger webhooks

Button Actions
Interactive buttons with webhook callbacks

Form Submissions
Collect user input with forms

Dropdown Selects
Channel, member, date/time pickers

LLM Integration
Easy integration with Claude, GPT, etc.

Webhook Events (Chatbot API)

Event
Trigger
Use Case

bot_notification
User messages bot or uses slash command
Process commands, integrate LLM

bot_installed
Bot added to account
Initialize bot state

interactive_message_actions
Button clicked
Handle button actions

chat_message.submit
Form submitted
Process form data

app_deauthorized
Bot removed
Cleanup

See: Webhook Events Reference

Message Card Components

Build rich interactive messages with these components:

Component
Description

header
Title and subtitle

message
Plain text

fields
Key-value pairs

actions
Buttons (Primary, Danger, Default styles)

section
Colored sidebar grouping

attachments
Images with links

divider
Horizontal line

form_field
Text input

dropdown
Select menu

date_picker
Date selection

See: Message Cards Reference 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

Sample Applications

Sample
Description
Link

Chatbot Quickstart
Official tutorial (recommended start)
GitHub

Claude Chatbot
AI chatbot with Anthropic Claude
GitHub

Unsplash Chatbot
Image search with database
GitHub

ERP Chatbot
Oracle ERP with scheduled alerts
GitHub

Task Manager
Full CRUD app
GitHub

See: Sample Applications Guide 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 for:

Nginx reverse proxy setup

Base path configuration

OAuth redirect URI setup

Limitations

Limit
Value

Message length
4,096 characters

File size
512 MB

Members per channel
10,000

Channels per user
500

Security Best Practices

Verify webhook signatures - Always validate using x-zm-signature header

Sanitize messages - Limit to 4096 chars, remove control characters

Validate JIDs - Check format: user@domain or channel@domain

Environment variables - Never hardcode credentials

Use HTTPS - Required for production webhooks

See: Security Best Practices

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/

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

Fast troubleshooting first: 5-Minute Runbook

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

For sending messages as a user account.

API Selection Guide - Confirm Team Chat API is right

Environment Setup - Get credentials

OAuth Setup Example - Implement authentication

Send Message Example - Send your first message

Path 2: Chatbot API (Interactive Bots)

For building interactive chatbots with rich messages.

API Selection Guide - Confirm Chatbot API is right

Environment Setup - Get credentials (including Bot JID)

Webhook Architecture - Understand webhook events

Chatbot Setup Example - Build your first bot

Message Cards Reference - Create rich messages

Core Concepts

Essential understanding for both APIs.

Document
Description

API Selection Guide
Choose Team Chat API vs Chatbot API

Environment Setup
Complete credentials and app configuration

Authentication Flows
OAuth vs Client Credentials

Webhook Architecture
How webhooks work (Chatbot API)

Message Card Structure
Card component hierarchy

Deployment Guide
Production deployment strategies

Security Best Practices
Secure your integration

Complete Examples

Working code for common scenarios.

Authentication

Example
Description

OAuth Setup
User OAuth flow implementation

Token Management
Refresh tokens, expiration handling

Basic Operations

Example
Description

Send Message
Team Chat API message sending

Chatbot Setup
Complete chatbot with webhooks

List Channels
Get user's channels

Create Channel
Create public/private channels

Interactive Features (Chatbot API)

Example
Description

Button Actions
Handle button clicks

Form Submissions
Process form data

Slash Commands
Create custom commands

Dropdown Selects
Channel/member pickers

Advanced Integration

Example
Description

LLM Integration
Integrate Claude/GPT

Scheduled Alerts
Cron + incoming webhooks

Database Integration
Store conversation state

Multi-Step Workflows
Complex user interactions

References

API Documentation

Reference
Description

API Reference
Pointers and common endpoints

Webhook Events
Event types and handling checklist

Message Cards
All card components

Error Codes
Error handling guide

Sample Applications

Reference
Description

Sample Applications
Sample app index/notes

Field Guides

Reference
Description

JID Formats
Understanding JID identifiers

Scopes Reference
Common scopes

Rate Limits
Throttling guidance

Troubleshooting

Guide
Description

Common Issues
Quick diagnostics and solutions

OAuth Issues
Authentication failures

Webhook Issues
Webhook debugging

Message Issues
Message sending problems

Deployment Issues
Production problems

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

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

Environment Variables

See references/environment-variables.md for standardized .env keys and where to find each value.