zoom-team-chat

Zoom Team Chat Development

Build powerful messaging integrations and interactive chatbots for Zoom Team Chat. This skill covers two distinct APIs - make sure to choose the right one for your use case.

For agent-driven MCP tooling that sends/edits messages or manages Team Chat channels through Zoom's hosted MCP server, use ../zoom-mcp/team-chat/SKILL.md. Keep this skill as the default for deterministic REST API implementation, chatbot apps, webhooks, retry logic, and production backend control.

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

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

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

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

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 

---

*Content truncated.*