/zoom-apps-sdk

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

1. **[Architecture](concepts/architecture.md)** - Frontend/backend pattern, embedded browser, deep linking 2. **[Quick Start](examples/quick-start.md)** - Complete working Express + SDK app 3. **[Running Contexts](concepts/running-contexts.md)** - Where your app runs (inMeeting, inMainClient, etc.) 4. **[Zoom Apps vs Meeting SDK](concepts/meeting-sdk-vs-zoom-apps.md)** - Stop mixing app types 4. **[In-Client OAuth](examples/in-client-oauth.md)** - Seamless authorization with PKCE 5. **[API Reference](references/apis.md)** - 100+ SDK methods 6. **Integrated Index** - see the section below in this file 7. **[5-Minute Runbook](RUNBOOK.md)** - Preflight checks before deep debugging

**Reference:**

• **[API Reference](references/apis.md)** - All SDK methods by category
• **[Events Reference](references/events.md)** - All SDK event listeners
• **[Layers API](references/layers-api.md)** - Immersive and camera mode rendering
• **[OAuth Reference](references/oauth.md)** - OAuth flows for Zoom Apps
• **[Zoom Mail](references/zmail-sdk.md)** - Mail plugin integration

**Having issues?**

• App won't load in Zoom → Check [Domain Allowlist](#url-whitelisting-required) below
• SDK errors → [Common Issues](troubleshooting/common-issues.md)
• Local dev setup → [Debugging Guide](troubleshooting/debugging.md)
• Version upgrade → [Migration Guide](troubleshooting/migration.md)
• Forum-derived FAQs → [Forum Top Questions](troubleshooting/forum-top-questions.md)

**Building immersive experiences?**

• [Layers Immersive Mode](examples/layers-immersive.md) - Custom video layouts
• [Camera Mode](examples/layers-camera.md) - Virtual camera overlays

> **Need help with OAuth?** See the **[zoom-oauth](../oauth/SKILL.md)** 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](https://marketplace.zoom.us/)
• 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);
    // 'inMeeting' | 'inMainClient' | 'inWebinar' | 'inImmersive' | ...

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

Critical: Global Variable Conflict

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

// WRONG - causes SyntaxError in Zoom's embedded browser
let zoomSdk = null;
zoomSdk = window.zoomSdk;

// CORRECT - use di