zoom-meeting-sdk-windows

# Zoom Meeting SDK (Windows) Embed Zoom meeting capabilities into Windows desktop applications for native C++ integrations and headless bots. ## New to Zoom SDK? Start Here! **The fastest way to master the SDK:** 1. **[SDK Architecture Pattern](concepts/sdk-architecture-pattern.md)** - Learn the universal pattern that works for ALL 35+ features 2. **[Authentication Pattern](examples/authentication-pattern.md)** - Get a working bot joining meetings 3. **[Windows Message Loop](troubleshooting/windows-message-loop.md)** - Fix the #1 reason callbacks don't fire **Building a Custom UI?** - [Custom UI Architecture](concepts/custom-ui-architecture.md) - How SDK rendering actually works (child HWNDs, D3D, etc.) - [Custom UI Video Rendering Example](examples/custom-ui-video-rendering.md) - Complete working code - [SDK-Rendered vs Self-Rendered](concepts/custom-ui-vs-raw-data.md) - Choose the right approach - [Custom UI Interface Methods](references/interface-methods.md) - All 13 required virtual methods **Having issues?** - Build errors → [Build Errors Guide](troubleshooting/build-errors.md) - Callbacks not firing → [Windows Message Loop](troubleshooting/windows-message-loop.md) - Quick diagnostics → [Common Issues](troubleshooting/common-issues.md) - Performance / service quality → [service-quality.md](examples/service-quality.md) - Deployment notes → [deployment.md](references/deployment.md) - MSBuild from git bash → [Build Errors Guide](troubleshooting/build-errors.md#msbuild-command-pattern) - Complete navigation → [SKILL.md](SKILL.md) ## Prerequisites - Zoom app with Meeting SDK credentials (Client ID & Secret) - Visual Studio 2019/2022 or later - Windows 10 or later - C++ development environment - vcpkg for dependency management > **Need help with authentication?** See the **[zoom-oauth](../../oauth/SKILL.md)** skill for JWT token generation. ## Project Preferences & Learnings > **IMPORTANT**: These are hard-won preferences from real project experience. Follow these when creating new projects. ### Do NOT use CMake — Use native Visual Studio `.vcxproj` **Always create a native Visual Studio `.sln` + `.vcxproj` project**, not a CMake project. Reasons: - More standard and familiar for Windows C++ developers - Developers can double-click the `.sln` to open in Visual Studio immediately - Project settings (include dirs, lib dirs, preprocessor defines) are easier to see and edit in the VS Property Pages UI - No extra CMake tooling or configuration step required - Friendlier and easier for developers to understand and maintain ### `config.json` must be visible in Solution Explorer The `config.json` file (containing `sdk_jwt`, `meeting_number`, `passcode`) must be: 1. **Included in the `.vcxproj`** as a `<None>` item with `<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>` 2. **Placed in a "Config" filter** in the `.vcxproj.filters` file so it appears under a "Config" folder in Solution Explorer 3. **Easily editable** by developers directly from Solution Explorer — they should never have to hunt for it in File Explorer Example `.vcxproj` entry: ```xml <ItemGroup> <None Include="config.json"> <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> </None> </ItemGroup> ``` Example `.vcxproj.filters` entry: ```xml <ItemGroup> <Filter Include="Config"> <UniqueIdentifier>{GUID-HERE}</UniqueIdentifier> </Filter> </ItemGroup> <ItemGroup> <None Include="config.json"> <Filter>Config</Filter> </None> </ItemGroup> ``` ## Overview The Windows SDK is a **C++ native SDK** designed for: - **Desktop applications** - Native Windows apps with full UI control - **Headless bots** - Join meetings without UI - **Raw media access** - Capture/send audio/video streams - **Local recording** - Record meetings locally or to cloud ### Key Architectural Insight The SDK follows a **universal 3-step pattern** for every feature: 1. **Get controller** (singleton): `meetingService->Get[Feature]Controller()` 2. **Implement event listener**: `class MyListener : public I[Feature]Event { ... }` 3. **Register and use**: `controller->SetEvent(listener)` then call methods **This works for ALL features**: audio, video, chat, recording, participants, screen sharing, breakout rooms, webinars, Q&A, polling, whiteboard, and 20+ more! Learn more: **[SDK Architecture Pattern Guide](concepts/sdk-architecture-pattern.md)** ## Quick Start ### 1. Download Windows SDK Download from [Zoom Marketplace](https://marketplace.zoom.us/): - Extract `zoom-meeting-sdk-windows_x86_64-{version}.zip` ### 2. Setup Project Structure ``` your-project/ YourApp/ SDK/ x64/ bin/ # DLL files and dependencies h/ # Header files lib/ # sdk.lib x86/ bin/ h/ lib/ YourApp.cpp YourApp.vcxproj config.json ``` Copy SDK files: ```cmd xcopy /E /I sdk-package\x64 your-project\YourApp\SDK\x64\ xcopy /E /I sdk-package\x86 your-project\YourApp\SDK\x86\ ``` ### 3. Install Dependencies (vcpkg) ```powershell # Install vcpkg git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg cd C:\vcpkg .\bootstrap-vcpkg.bat .\vcpkg integrate install # Install dependencies .\vcpkg install jsoncpp:x64-windows .\vcpkg install curl:x64-windows ``` ### 4. Configure Visual Studio Project **Project Properties → C/C++ → General → Additional Include Directories:** ``` $(SolutionDir)SDK\$(PlatformTarget)\h C:\vcpkg\packages\jsoncpp_x64-windows\include C:\vcpkg\packages\curl_x64-windows\include ``` **Project Properties → Linker → General → Additional Library Directories:** ``` $(SolutionDir)SDK\$(PlatformTarget)\lib ``` **Project Properties → Linker → Input → Additional Dependencies:** ``` sdk.lib ``` **Post-Build Event** (Copy DLLs to output): ```cmd xcopy /Y /D "$(SolutionDir)SDK\$(PlatformTarget)\bin\*.*" "$(OutDir)" ``` ### 5. Configure Credentials Create `config.json`: ```json { "sdk_jwt": "YOUR_JWT_TOKEN", "meeting_number": "1234567890", "passcode": "password123", "zak": "" } ``` ### 6. Build & Run - Open solution in Visual Studio - Select x64 or x86 configuration - Press F5 to build and run ## Core Workflow ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ InitSDK │───►│ AuthSDK │───►│ JoinMeeting │───►│ Raw Data │ │ │ │ (JWT) │ │ │ │ Subscribe │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ▼ ▼ OnAuthComplete onInMeeting callback callback ``` **⚠️ CRITICAL**: Add Windows message loop or callbacks won't fire! ```cpp while (!done) { MSG msg; while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) { TranslateMessage(&msg); DispatchMessage(&msg); } std::this_thread::sleep_for(std::chrono::milliseconds(100)); } ``` See: [Windows Message Loop Guide](troubleshooting/windows-message-loop.md) ## Code Examples > **💡 Pro Tip**: These are minimal examples. For complete, tested code see: > - [Authentication Pattern](examples/authentication-pattern.md) - Full auth workflow > - [Raw Video Capture](examples/raw-video-capture.md) - Complete video capture > - [SDK Architecture Pattern](concepts/sdk-architecture-pattern.md) - Implement any feature ### Important: Include Order **CRITICAL**: Include headers in this exact order or you'll get build errors: ```cpp #include <windows.h> // MUST be first #include <cstdint> // MUST be second (SDK headers use uint32_t) // ... other standard headers ... #include <zoom_sdk.h> #include <meeting_service_components/meeting_audio_interface.h> // BEFORE participants! #include <meeting_service_components/meeting_participants_ctrl_interface.h> ``` See: [Build Errors Guide](troubleshooting/build-errors.md) for all dependency fixes. ### 1. Initialize SDK ```cpp #include <windows.h> #include <cstdint> #include <zoom_sdk.h> using namespace ZOOM_SDK_NAMESPACE; bool InitMeetingSDK() { InitParam initParam; initParam.strWebDomain = L"https://zoom.us"; initParam.strSupportUrl = L"https://zoom.us"; initParam.emLanguageID = LANGUAGE_English; initParam.enableLogByDefault = true; initParam.enableGenerateDump = true; SDKError err = InitSDK(initParam); if (err != SDKERR_SUCCESS) { std::wcout << L"InitSDK failed: " << err << std::endl; return false; } return true; } ``` ### 2. Authenticate with JWT ```cpp #include <windows.h> #include <cstdint> #include <auth_service_interface.h> #include "AuthServiceEventListener.h" IAuthService* authService = nullptr; void OnAuthenticationComplete() { std::cout << "Authentication successful!" << std::endl; JoinMeeting(); // Proceed to join meeting } bool AuthenticateSDK(const std::wstring& jwtToken) { CreateAuthService(&authService); if (!authService) return false; // Set event listener BEFORE calling SDKAuth authService->SetEvent(new AuthServiceEventListener(&OnAuthenticationComplete)); // Authenticate with JWT AuthContext authContext; authContext.jwt_token = jwtToken.c_str(); SDKError err = authService->SDKAuth(authContext); if (err != SDKERR_SUCCESS) { std::wcout << L"SDKAuth failed: " << err << std::endl; return false; } // CRITICAL: Add message loop or callback won't fire! // See complete example: examples/authentication-pattern.md return true; } ``` **AuthServiceEventListener.h:** ```cpp #include <windows.h> #include <cstdint> #include <auth_service_interface.h> #include <iostream> using namespace ZOOM_SDK_NAMESPACE; class AuthServiceEventListener : public IAuthServiceEvent { public: AuthServiceEventListener(void (*onComplete)()) : onAuthComplete(onComplete) {} void onAuthenticationReturn(AuthResult ret) override { if (ret == AUTHRET_SUCCESS && onAuthComplete) { onAuthComplete(); } else { std::cout << "Auth failed: " << ret << std::endl; } } // Must implement ALL pure virtual methods (6 total) void onLoginReturnWithReason(LOGINSTATUS ret, IAccountInfo* info, LoginFailReason reason) override {} void onLogout() override {} void onZoomIdentityExpired() override {} void onZoomAuthIdentityExpired() override {} #if defined(WIN32) void onNotificationServiceStatus(SDKNotificationServiceStatus status, SDKNotificationServiceError error) override {} #endif private: void (*onAuthComplete)(); }; ``` **See complete working code**: [Authentication Pattern Guide](examples/authentication-pattern.md) ### 3. Join Meeting ```cpp #include <meeting_service_interface.h> #include "MeetingServiceEventListener.h" IMeetingService* meetingService = nullptr; void OnMeetingJoined() { std::cout << "Joining meeting..." << std::endl; } void OnInMeeting() { std::cout << "In meeting now!" << std::endl; // Start raw data capture here } void OnMeetingEnds() { std::cout << "Meeting ended" << std::endl; } bool JoinMeeting(UINT64 meetingNumber, const std::wstring& password) { CreateMeetingService(&meetingService); if (!meetingService) return false; // Set event listener meetingService->SetEvent( new MeetingServiceEventListener(&OnMeetingJoined, &OnMeetingEnds, &OnInMeeting) ); // Prepare join parameters JoinParam joinParam; joinParam.userType = SDK_UT_WITHOUT_LOGIN; JoinParam4WithoutLogin& params = joinParam.param.withoutloginuserJoin; params.meetingNumber = meetingNumber; params.userName = L"Bot User"; params.psw = password.c_str(); params.isVideoOff = false; params.isAudioOff = false; SDKError err = meetingService->Join(joinParam); if (err != SDKERR_SUCCESS) { std::wcout << L"Join failed: " << err << std::endl; return false; } return true; } ``` **MeetingServiceEventListener.h:** ```cpp #include <windows.h> #include <cstdint> #include <meeting_service_interface.h> #include <iostream> using namespace ZOOM_SDK_NAMESPACE; class MeetingServiceEventListener : public IMeetingServiceEvent { public: MeetingServiceEventListener( void (*onJoined)(), void (*onEnded)(), void (*onInMeeting)() ) : onMeetingJoined(onJoined), onMeetingEnded(onEnded), onInMeetingCallback(onInMeeting) {} void onMeetingStatusChanged(MeetingStatus status, int iResult) override { if (status == MEETING_STATUS_CONNECTING) { if (onMeetingJoined) onMeetingJoined(); }