OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add anthropics/knowledge-work-plugins --skill zoom-apps-sdk
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.
npx skills add anthropics/knowledge-work-plugins --skill 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.
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
New to Zoom Apps? Follow this path:
Reference:
Having issues?
Building immersive experiences?
Need help with OAuth? See the zoom-oauth skill for authentication flows.
The Zoom Apps SDK (@zoom/appssdk) provides JavaScript APIs for web apps running in Zoom's embedded browser:
The CDN script defines window.zoomSdk globally. Do NOT redeclare it:
This only applies to the CDN approach. The NPM import creates a module-scoped variable, no conflict.
The SDK only functions inside the Zoom client. When accessed in a regular browser:
window.zoomSdk exists but sdk.config() throws an errorYour app will NOT load in Zoom unless the domain is whitelisted.
yourdomain.com for production, xxxxx.ngrok.io for dev)Without this, the Zoom client shows a blank panel with no error message.
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.
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.
Every Zoom App starts with config():
Rules:
config() MUST be called before any other SDK methodconfig() are availableunsupportedApis for graceful degradationBest UX for authorization - no browser redirect:
See In-Client OAuth Guide for complete implementation.
Build immersive video layouts and camera overlays:
See Layers Immersive and Camera Mode.
| 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) |
| 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 |
| Repository | Type | Last Updated | Status | SDK Version |
|---|---|---|---|---|
| zoomapps-sample-js | Hello World (Vanilla JS) | Dec 2025 | Active | ^0.16.26 |
| zoomapps-advancedsample-react | Advanced (React + Redis) | Oct 2025 | Active | 0.16.0 |
| zoomapps-customlayout-js | Layers API | Nov 2023 | Stale | ^0.16.8 |
| zoomapps-texteditor-vuejs | Collaborate (Vue + Y.js) | Oct 2023 | Stale | ^0.16.7 |
| zoomapps-serverless-vuejs | Serverless (Firebase) | Aug 2024 | Stale | ^0.16.21 |
| zoomapps-cameramode-vuejs | Camera Mode | - | - | - |
| zoomapps-workshop-sample | Workshop | - | - | - |
Recommended for new projects: Use @zoom/appssdk version ^0.16.26.
| Type | Repository | Description |
|---|---|---|
| Library | harvard-edtech/zaccl | Zoom App Complete Connection Library |
Full list: See general/references/community-repos.md
zoomapps-sample-js - Simplest, most up-to-datezoomapps-advancedsample-react - Comprehensive (In-Client OAuth, Guest Mode, Collaborate)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.
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.
Only APIs listed in config({ capabilities: [...] }) are available. Calling an unlisted API throws an error. This is also true for event listeners.
zoomSdk.config() throws outside the Zoom client. Always wrap in try/catch with browser fallback:
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.
Use zoomSdk.authorize() (In-Client) for best UX - no browser redirect. Only fall back to web redirect for initial install from Marketplace.
Camera mode uses CEF which takes time to initialize. drawImage/drawWebView may fail if called too early. Implement retry with exponential backoff.
Zoom's embedded browser requires cookies with SameSite=None and Secure=true. Without this, sessions break silently.
Always validate the OAuth state parameter to prevent CSRF attacks. Generate cryptographically random state, store it, and verify on callback.
Need help? Start with Integrated Index section below for complete navigation.
This section was migrated from SKILL.md.
If you're new to Zoom Apps, follow this order:
Run preflight checks first -> RUNBOOK.md
Read the architecture -> concepts/architecture.md
Build your first app -> examples/quick-start.md
Understand running contexts -> concepts/running-contexts.md
Implement OAuth -> examples/in-client-oauth.md
Add features -> references/apis.md
Troubleshoot -> troubleshooting/common-issues.md
Understand how Zoom Apps work: Frontend in embedded browser, backend for OAuth/API, SDK as the bridge. Without this, nothing else makes sense.
Complete working code. Get something running before diving into advanced features.
troubleshooting/common-issues.md
90% of Zoom Apps issues are: domain allowlist, global variable conflict, or missing capabilities.
Global Variable Conflict is the #1 Gotcha
window.zoomSdk globallylet zoomSdk = ... causes SyntaxError in Zoom's browserlet sdk = window.zoomSdk or NPM importDomain Allowlist is Non-Negotiable
appssdk.zoom.us AND any CDN domainsconfig() Gates Everything
unsupportedApis for client version compatibilityIn-Client OAuth > Web OAuth for UX
authorize() keeps user in Zoom (no browser redirect)Two App Instances Can Run Simultaneously
connect() + postMessage() to sync between themCamera Mode Has CEF Quirks
Cookie Settings Matter
SameSite=None + Secure=true required-> Domain Allowlist - add domain to Marketplace
-> Global Variable - use let sdk = window.zoomSdk
-> Browser Preview - SDK only works inside Zoom
-> OAuth Scopes - add required scopes in Marketplace
-> API Reference - find the method, check capabilities needed
-> Debugging Guide - ngrok + Marketplace config
Based on @zoom/appssdk v0.16.x (latest: 0.16.26+)
Happy coding!
Start with Architecture to understand the pattern, then Quick Start to build your first app.
<script src="https://appssdk.zoom.us/sdk.js"></script>
<script>
// CRITICAL: Do NOT declare "let zoomSdk" - the SDK defines window.zoomSdk globally
// Using "let zoomSdk = ..." causes: SyntaxError: redeclaration of non-configurable global property
let sdk = window.zoomSdk; // Use a different variable name
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>// WRONG - causes SyntaxError in Zoom's embedded browser
let zoomSdk = null;
zoomSdk = window.zoomSdk;
// CORRECT - use different variable name
let sdk = window.zoomSdk;
// ALSO CORRECT - NPM import (no conflict)
import zoomSdk from '@zoom/appssdk';import zoomSdk from '@zoom/appssdk';
const configResponse = await zoomSdk.config({
capabilities: [
// List ALL APIs you will use
'getMeetingContext',
'getUserContext',
'shareApp',
'openUrl',
'authorize',
'onAuthorized'
],
version: '0.16'
});
// configResponse contains:
// {
// runningContext: 'inMeeting',
// clientVersion: '5.x.x',
// unsupportedApis: [] // APIs not supported in this client version
// }// 1. Get code challenge from your backend
const { codeChallenge, state } = await fetch('/api/auth/challenge').then(r => r.json());
// 2. Trigger in-client authorization
await zoomSdk.authorize({ codeChallenge, state });
// 3. Listen for authorization result
zoomSdk.addEventListener('onAuthorized', async (event) => {
const { code, state } = event;
// 4. Send code to backend for token exchange
await fetch('/api/auth/token', {
method: 'POST',
body: JSON.stringify({ code, state })
});
});// Start immersive mode - replaces gallery view
await zoomSdk.runRenderingContext({ view: 'immersive' });
// Position participant video feeds
await zoomSdk.drawParticipant({
participantUUID: 'user-uuid',
x: 0, y: 0, width: 640, height: 480, zIndex: 1
});
// Add overlay images
await zoomSdk.drawImage({
imageData: canvas.toDataURL(),
x: 0, y: 0, width: 1280, height: 720, zIndex: 0
});
// Exit immersive mode
await zoomSdk.closeRenderingContext();try { await zoomSdk.config({...}); } catch { showBrowserPreview(); }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