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