| name | zoom-apps-sdk |
| description | Reference skill for Zoom Apps SDK. Use after routing to an in-client app workflow when building web apps that run inside Zoom meetings, webinars, the main client, or Zoom Phone. |
| user-invocable | false |
| triggers | ["zoom app","in-meeting app","app inside zoom","zoom client app","layers api","immersive mode","camera mode","collaborate mode","appssdk","in-client oauth","zoom mail","domain allowlist","domain whitelist","url whitelisting","blank panel","runningContext","zoomSdk"] |
Zoom Apps SDK
Background reference for web apps that run inside the Zoom client. Prefer choose-zoom-approach first, then route here for Layers API, Collaborate Mode, in-client OAuth, and runtime constraints.
Zoom Apps SDK
Build web apps that run inside the Zoom client - meetings, webinars, main client, and Zoom Phone.
Official Documentation: https://developers.zoom.us/docs/zoom-apps/
SDK Reference: https://appssdk.zoom.us/
NPM Package: https://www.npmjs.com/package/@zoom/appssdk
Quick Links
New to Zoom Apps? Follow this path:
- Architecture - Frontend/backend pattern, embedded browser, deep linking
- Quick Start - Complete working Express + SDK app
- Running Contexts - Where your app runs (inMeeting, inMainClient, etc.)
- Zoom Apps vs Meeting SDK - Stop mixing app types
- In-Client OAuth - Seamless authorization with PKCE
- API Reference - 100+ SDK methods
- Integrated Index - see the section below in this file
- 5-Minute Runbook - Preflight checks before deep debugging
Reference:
Having issues?
Building immersive experiences?
Need help with OAuth? See the zoom-oauth skill for authentication flows.
SDK Overview
The Zoom Apps SDK (@zoom/appssdk) provides JavaScript APIs for web apps running in Zoom's embedded browser:
- Context APIs - Get meeting, user, and participant info
- Meeting Actions - Share app, invite participants, open URLs
- Authorization - In-Client OAuth with PKCE (no browser redirect)
- Layers API - Immersive video layouts and camera mode overlays
- Collaborate Mode - Shared app state across participants
- App Communication - Message passing between app instances (main client <-> meeting)
- Media Controls - Virtual backgrounds, camera listing, recording control
- UI Controls - Expand app, notifications, popout
- Events - React to meeting state, participants, sharing, and more
Prerequisites
- Zoom app configured as "Zoom App" type in Marketplace
- OAuth credentials (Client ID + Secret) with Zoom Apps scopes
- Web application (Node.js + Express recommended)
- Your domain whitelisted in Marketplace domain allowlist
- ngrok or HTTPS tunnel for local development
- Node.js 18+ (for the backend server)
Quick Start
Option A: NPM (Recommended for frameworks)
npm install @zoom/appssdk
import zoomSdk from '@zoom/appssdk';
async function init() {
try {
const configResponse = await zoomSdk.config({
capabilities: [
'shareApp',
'getMeetingContext',
'getUserContext',
'openUrl'
],
version: '0.16'
});
console.log('Running context:', configResponse.runningContext);
const context = await zoomSdk.getMeetingContext();
console.log('Meeting ID:', context.meetingID);
} catch (error) {
console.error('Not running inside Zoom:', error.message);
showDemoMode();
}
}
Option B: CDN (Vanilla JS)
<script src="https://appssdk.zoom.us/sdk.js"></script>
<script>
let sdk = window.zoomSdk;
async function init() {
try {
const configResponse = await sdk.config({
capabilities: ['shareApp', 'getMeetingContext', 'getUserContext'],
version: '0.16'
});
console.log('Running context:', configResponse.runningContext);
} catch (error) {
console.error('Not running inside Zoom:', error.message);
showDemoMode();
}
}
function showDemoMode() {
document.body.innerHTML = '<h1>Preview Mode</h1><p>Open this app inside Zoom to use.</p>';
}
document.addEventListener('DOMContentLoaded', () => {
init();
setTimeout(() => { if (!sdk) showDemoMode(); }, 3000);
});
</script>
Critical: Global Variable Conflict
The CDN script defines window.zoomSdk globally. Do NOT redeclare it:
let zoomSdk = null;
zoomSdk = window.zoomSdk;
let sdk = window.zoomSdk;
import zoomSdk from '@zoom/appssdk';
This only applies to the CDN approach. The NPM import creates a module-scoped variable, no conflict.
Browser Preview / Demo Mode
The SDK only functions inside the Zoom client. When accessed in a regular browser:
window.zoomSdk exists but sdk.config() throws an error- Always implement try/catch with fallback UI
- Add timeout (3 seconds) in case SDK hangs
URL Whitelisting (Required)
Your app will NOT load in Zoom unless the domain is whitelisted.
- Go to Zoom Marketplace
- Open your app -> Feature tab
- Under Zoom App, find Add Allow List
- Add your domain (e.g.,
yourdomain.com for production, xxxxx.ngrok.io for dev)
Without this, the Zoom client shows a blank panel with no error message.
OAuth Scopes (Required)
Capabilities require matching OAuth scopes enabled in Marketplace:
| Capability | Required Scope |
|---|
getMeetingContext | zoomapp:inmeeting |
getUserContext | zoomapp:inmeeting |
shareApp | zoomapp:inmeeting |
openUrl | zoomapp:inmeeting |
sendAppInvitation | zoomapp:inmeeting |
runRenderingContext | zoomapp:inmeeting |
authorize | zoomapp:inmeeting |
getMeetingParticipants | zoomapp:inmeeting |
To add scopes: Marketplace -> Your App -> Scopes tab -> Add required scopes.
Missing scopes = capability fails silently or throws error. Users must re-authorize if you add new scopes.
Running Contexts
Your app runs in different surfaces within Zoom. The configResponse.runningContext tells you where:
| Context | Surface | Description |
|---|
inMeeting | Meeting sidebar | Most common. Full meeting APIs available |
inMainClient | Main client panel | Home tab. No meeting context APIs |
inWebinar | Webinar sidebar | Host/panelist. Meeting + webinar APIs |
inImmersive | Layers API | Full-screen custom rendering |
inCamera | Camera mode | Virtual camera overlay |
inCollaborate | Collaborate mode | Shared state context |
inPhone | Zoom Phone | Phone call app |
inChat | Team Chat | Chat sidebar |
See Running Contexts for context-specific behavior and APIs.
SDK Initialization Pattern
Every Zoom App starts with config():
import zoomSdk from '@zoom/appssdk';
const configResponse = await zoomSdk.config({
capabilities: [
'getMeetingContext',
'getUserContext',
'shareApp',
'openUrl',
'authorize',
'onAuthorized'
],
version: '0.16'
});
Rules:
config() MUST be called before any other SDK method- Only capabilities listed in
config() are available
- Capabilities must match OAuth scopes in Marketplace
- Check
unsupportedApis for graceful degradation
In-Client OAuth (Summary)
Best UX for authorization - no browser redirect:
const { codeChallenge, state } = await fetch('/api/auth/challenge').then(r => r.json());
await zoomSdk.authorize({ codeChallenge, state });
zoomSdk.addEventListener('onAuthorized', async (event) => {
const { code, state } = event;
await fetch('/api/auth/token', {
method: 'POST',
body: JSON.stringify({ code, state })
});
});
See In-Client OAuth Guide for complete implementation.
Layers API (Summary)
Build immersive video layouts and camera overlays:
await zoomSdk.runRenderingContext({ view: 'immersive' });
await zoomSdk.drawParticipant({
participantUUID: 'user-uuid',
x: 0, y: 0, width: 640, height: 480, zIndex: 1
});
await zoomSdk.drawImage({
imageData: canvas.toDataURL(),
x: 0, y: 0, width: 1280, height: 720, zIndex: 0
});
await zoomSdk.closeRenderingContext();
See Layers Immersive and Camera Mode.
Environment Variables
| Variable | Description | Where to Find |
|---|
ZOOM_APP_CLIENT_ID | App client ID | Marketplace -> App -> App Credentials |
ZOOM_APP_CLIENT_SECRET | App client secret | Marketplace -> App -> App Credentials |
ZOOM_APP_REDIRECT_URI | OAuth redirect URL | Your server URL + /auth |
SESSION_SECRET | Cookie signing secret | Generate random string |
ZOOM_HOST | Zoom host URL | https://zoom.us (or https://zoomgov.com) |
Common APIs
| API | Description |
|---|
config() | Initialize SDK, request capabilities |
getMeetingContext() | Get meeting ID, topic, status |
getUserContext() | Get user name, role, participant ID |
getRunningContext() | Get current running context |
getMeetingParticipants() | List participants |
shareApp() | Share app screen with participants |
openUrl({ url }) | Open URL in external browser |
sendAppInvitation() | Invite users to open your app |
authorize() | Trigger In-Client OAuth |
connect() | Connect to other app instances |
postMessage() | Send message to connected instances |
runRenderingContext() | Start Layers API (immersive/camera) |
expandApp({ action }) | Expand/collapse app panel |
showNotification() | Show notification in Zoom |
Complete Documentation Library
Core Concepts
- Architecture - Frontend/backend pattern, embedded browser, deep linking, X-Zoom-App-Context
- Running Contexts - All contexts, context-specific APIs, multi-instance communication
- Security - OWASP headers, CSP, cookie security, PKCE, token storage
Complete Examples
Troubleshooting
References
Sample Repositories
Official (by Zoom)
Recommended for new projects: Use @zoom/appssdk version ^0.16.26.
Community
Full list: See general/references/community-repos.md
Learning Path
- Start:
zoomapps-sample-js - Simplest, most up-to-date
- Advanced:
zoomapps-advancedsample-react - Comprehensive (In-Client OAuth, Guest Mode, Collaborate)
- Specialized: Pick based on feature (Layers, Serverless, Camera Mode)
Critical Gotchas (From Real Development)
1. Global Variable Conflict
The CDN script defines window.zoomSdk. Declaring let zoomSdk in your code causes SyntaxError: redeclaration of non-configurable global property. Use let sdk = window.zoomSdk or the NPM import.
2. Domain Allowlist
Your app URL must be in the Marketplace domain allowlist. Without it, Zoom shows a blank panel with no error. Also add appssdk.zoom.us and any CDN domains you use.
3. Capabilities Must Be Listed
Only APIs listed in config({ capabilities: [...] }) are available. Calling an unlisted API throws an error. This is also true for event listeners.
4. SDK Only Works Inside Zoom
zoomSdk.config() throws outside the Zoom client. Always wrap in try/catch with browser fallback:
try { await zoomSdk.config({...}); } catch { showBrowserPreview(); }
5. ngrok URL Changes
Free ngrok URLs change on restart. You must update 4 places in Marketplace: Home URL, Redirect URL, OAuth Allow List, Domain Allow List. Consider ngrok paid plan for stable subdomain.
6. In-Client OAuth vs Web OAuth
Use zoomSdk.authorize() (In-Client) for best UX - no browser redirect. Only fall back to web redirect for initial install from Marketplace.
7. Camera Mode CEF Race Condition
Camera mode uses CEF which takes time to initialize. drawImage/drawWebView may fail if called too early. Implement retry with exponential backoff.
8. Cookie Configuration
Zoom's embedded browser requires cookies with SameSite=None and Secure=true. Without this, sessions break silently.
9. State Validation
Always validate the OAuth state parameter to prevent CSRF attacks. Generate cryptographically random state, store it, and verify on callback.
Resources
Need help? Start with Integrated Index section below for complete navigation.
Integrated Index
This section was migrated from SKILL.md.
Quick Start Path
If you're new to Zoom Apps, follow this order:
-
Run preflight checks first -> RUNBOOK.md
-
Read the architecture -> concepts/architecture.md
- Frontend/backend pattern, embedded browser, deep linking
- Understand how Zoom loads and communicates with your app
-
Build your first app -> examples/quick-start.md
- Complete Express + SDK Hello World
- ngrok setup for local development
-
Understand running contexts -> concepts/running-contexts.md
- Where your app runs (inMeeting, inMainClient, inWebinar, etc.)
- Context-specific APIs and limitations
-
Implement OAuth -> examples/in-client-oauth.md
- In-Client OAuth with PKCE (best UX)
- Token exchange and storage
-
Add features -> references/apis.md
- 100+ SDK methods organized by category
- Code examples for each
-
Troubleshoot -> troubleshooting/common-issues.md
- Quick diagnostics for common problems
Documentation Structure
zoom-apps-sdk/
├── SKILL.md # Main skill overview
├── SKILL.md # This file - navigation guide
│
├── concepts/ # Core architectural patterns
│ ├── architecture.md # Frontend/backend, embedded browser, OAuth flow
│ ├── running-contexts.md # Where your app runs + context-specific APIs
│ └── security.md # OWASP headers, CSP, data access layers
│
├── examples/ # Complete working code
│ ├── quick-start.md # Hello World - minimal Express + SDK app
│ ├── in-client-oauth.md # In-Client OAuth with PKCE
│ ├── layers-immersive.md # Layers API - immersive mode (custom layouts)
│ ├── layers-camera.md # Layers API - camera mode (virtual camera)
│ ├── collaborate-mode.md # Collaborate mode (shared state)
│ ├── guest-mode.md # Guest mode (unauthenticated -> authorized)
│ ├── breakout-rooms.md # Breakout room integration
│ └── app-communication.md # connect + postMessage between instances
│
├── troubleshooting/ # Problem solving guides
│ ├── common-issues.md # Quick diagnostics, error codes
│ ├── debugging.md # Local dev setup, ngrok, browser preview
│ └── migration.md # SDK version migration notes
│
└── references/ # Reference documentation
├── apis.md # Complete API reference (100+ methods)
├── events.md # All SDK events
├── layers-api.md # Layers API detailed reference
├── oauth.md # OAuth flows for Zoom Apps
└── zmail-sdk.md # Zoom Mail integration
By Use Case
I want to build a basic Zoom App
- Architecture - Understand the pattern
- Quick Start - Build Hello World
- In-Client OAuth - Add authorization
- Security - Required headers
I want immersive video layouts (Layers API)
- Layers Immersive - Custom video positions
- Layers API Reference - All drawing methods
- App Communication - Sync layout across participants
I want a virtual camera overlay
- Camera Mode - Camera mode rendering
- Layers API Reference - Drawing methods
I want real-time collaboration
- Collaborate Mode - Shared state APIs
- App Communication - Instance messaging
I want guest/anonymous access
- Guest Mode - Three authorization states
- In-Client OAuth - promptAuthorize flow
I want breakout room support
- Breakout Rooms - Room detection and state sync
I want to sync between main client and meeting
- App Communication - connect + postMessage
- Running Contexts - Multi-instance behavior
I want serverless deployment
- Quick Start - Understand the base pattern first
- Sample: zoomapps-serverless-vuejs - Firebase pattern
I want to add Zoom Mail integration
- Zoom Mail Reference - REST API + mail plugins
I'm getting errors
- Common Issues - Quick diagnostic table
- Debugging - Local dev setup, DevTools
- Migration - Version compatibility
Most Critical Documents
1. Architecture (FOUNDATION)
concepts/architecture.md
Understand how Zoom Apps work: Frontend in embedded browser, backend for OAuth/API, SDK as the bridge. Without this, nothing else makes sense.
2. Quick Start (FIRST APP)
examples/quick-start.md
Complete working code. Get something running before diving into advanced features.
3. Common Issues (MOST COMMON PROBLEMS)
troubleshooting/common-issues.md
90% of Zoom Apps issues are: domain allowlist, global variable conflict, or missing capabilities.
Key Learnings
Critical Discoveries:
-
Global Variable Conflict is the #1 Gotcha
- CDN script defines
window.zoomSdk globally
let zoomSdk = ... causes SyntaxError in Zoom's browser- Use
let sdk = window.zoomSdk or NPM import
-
Domain Allowlist is Non-Negotiable
- App shows blank panel with zero error if domain not whitelisted
- Must include your domain AND
appssdk.zoom.us AND any CDN domains
- ngrok URLs change on restart - must update Marketplace each time
-
config() Gates Everything
- Must be called first, must list all capabilities
- Unlisted capabilities throw errors
- Check
unsupportedApis for client version compatibility
-
In-Client OAuth > Web OAuth for UX
authorize() keeps user in Zoom (no browser redirect)- Web redirect only needed for initial Marketplace install
- Always implement PKCE (code_verifier + code_challenge)
-
Two App Instances Can Run Simultaneously
- Main client instance + meeting instance
- Use
connect() + postMessage() to sync between them
- Pre-meeting setup in main client, use in meeting
-
Camera Mode Has CEF Quirks
- CEF initialization takes time
- Draw calls may fail if too early
- Use retry with exponential backoff
-
Cookie Settings Matter
SameSite=None + Secure=true required- Without this, sessions silently fail in embedded browser
Quick Reference
"App shows blank panel"
-> Domain Allowlist - add domain to Marketplace
"SyntaxError: redeclaration"
-> Global Variable - use let sdk = window.zoomSdk
"config() throws error"
-> Browser Preview - SDK only works inside Zoom
"API call fails silently"
-> OAuth Scopes - add required scopes in Marketplace
"How do I implement [feature]?"
-> API Reference - find the method, check capabilities needed
"How do I test locally?"
-> Debugging Guide - ngrok + Marketplace config
Document Version
Based on @zoom/appssdk v0.16.x (latest: 0.16.26+)
Operations
- RUNBOOK.md - 5-minute preflight and debugging checklist.
