Labsco
anthropics logo

zoom-apps-sdk

✓ Official★ 22,300

by anthropic · part of anthropics/knowledge-work-plugins

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…

🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup
#automation#devops#git#search#finance#security
🧩 One of 7 skills in the anthropics/knowledge-work-plugins package — works on its own, and pairs well with its siblings.

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…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by anthropic

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… npx skills add https://github.com/anthropics/knowledge-work-plugins --skill zoom-apps-sdk Download ZIPGitHub22.3k

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:

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

Critical: Global Variable Conflict

The CDN script defines window.zoomSdk globally. Do NOT redeclare it:

Copy & paste — that's it
// 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';

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.

SDK Initialization Pattern

Every Zoom App starts with config():

Copy & paste — that's it
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
// }

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:

Copy & paste — that's it
// 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 })
 });
});

See In-Client OAuth Guide for complete implementation.

Layers API (Summary)

Build immersive video layouts and camera overlays:

Copy & paste — that's it
// 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();

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)

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.

Community

Type Repository Description Library harvard-edtech/zaccl Zoom App Complete Connection Library

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:

Copy & paste — that's it
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.

Documentation Structure

Copy & paste — that's it
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

I want immersive video layouts (Layers API)

I want a virtual camera overlay

I want real-time collaboration

I want guest/anonymous access

I want breakout room support

I want to sync between main client and meeting

I want serverless deployment

I want to add Zoom Mail integration

I'm getting errors

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+)

Happy coding!

Start with Architecture to understand the pattern, then Quick Start to build your first app.