zoom-apps-sdk

SKILL.md

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:

API Reference - All SDK methods by category

Events Reference - All SDK event listeners

Layers API - Immersive and camera mode rendering

OAuth Reference - OAuth flows for Zoom Apps

Zoom Mail - Mail plugin integration

Having issues?

App won't load in Zoom → Check Domain Allowlist below

SDK errors → Common Issues

Local dev setup → Debugging Guide

Version upgrade → Migration Guide

Forum-derived FAQs → Forum Top Questions

Building immersive experiences?

Layers Immersive Mode - Custom video layouts

Camera Mode - Virtual camera overlays

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);
    // '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 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.

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

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

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

Quick Start - Hello World Express + SDK app

In-Client OAuth - PKCE authorization flow

Layers Immersive - Custom video layouts

Camera Mode - Virtual camera overlays

Collaborate Mode - Shared state across participants

Guest Mode - Unauthenticated/authenticated/authorized states

Breakout Rooms - Room detection and cross-room state

App Communication - connect + postMessage between instances

Troubleshooting

Common Issues - Quick diagnostics and error codes

Debugging - Local dev, ngrok, browser preview

Migration - SDK version upgrade notes

References

API Reference - All 100+ SDK methods

Events Reference - All SDK event listeners

Layers API Reference - Drawing and rendering methods

OAuth Reference - OAuth flows for Zoom Apps

Zoom Mail - Mail plugin integration

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:

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

Official docs: https://developers.zoom.us/docs/zoom-apps/

SDK reference: https://appssdk.zoom.us/

NPM package: https://www.npmjs.com/package/@zoom/appssdk

Developer forum: https://devforum.zoom.us/

GitHub SDK source: https://github.com/zoom/appssdk

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

Happy coding!

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