Rivet Sdk

Zoom Rivet SDK

Background reference for Zoom Rivet as a JavaScript and TypeScript server framework for Zoom integrations.

Implementation guidance for Zoom Rivet (JavaScript/TypeScript) as a server-side framework for:

• OAuth and token handling
• Webhook event consumption
• Typed REST API endpoint wrappers
• Multi-module server composition

Official docs:

• https://developers.zoom.us/docs/rivet/
• https://developers.zoom.us/docs/rivet/javascript/
• https://zoom.github.io/rivet-javascript/

Reference samples:

• https://github.com/zoom/rivet-javascript-sample
• https://github.com/zoom/isv-rivet-starter
• https://github.com/zoom/Rivet-Server-Sample
• https://github.com/zoom/rivet-javascript

Routing Guardrail

• Rivet SDK is a Node.js framework that bundles Zoom auth handling, webhook receivers, and typed API wrappers.
• Rivet is recommended for faster server-side scaffolding, but it is not mandatory.
• At planning start, confirm preference:
• Do you want Rivet SDK, or direct OAuth + REST without Rivet?
• Use Rivet when the user wants a Node.js server that combines Zoom auth + webhooks + API calls with minimal glue code.
• If the user only needs direct API calls from an existing backend, chain with ../rest-api/SKILL.md.
• If the user is focused on Zoom Team Chat app cards/commands behavior, chain with ../team-chat/SKILL.md.
• If the user needs SDK embed (Meeting SDK/Video SDK client runtime), route to ../meeting-sdk/SKILL.md or ../video-sdk/SKILL.md.

Quick Links

Start here: 1. concepts/architecture-and-lifecycle.md 2. scenarios/high-level-scenarios.md 3. examples/getting-started-pattern.md 4. examples/multi-client-pattern.md 5. references/rivet-reference-map.md 6. references/versioning-and-compatibility.md 7. references/samples-validation.md 8. references/source-map.md 9. references/environment-variables.md 10. troubleshooting/common-issues.md 11. RUNBOOK.md 12. rivet-sdk.md

Common Lifecycle Pattern

1. Choose modules and auth model per module (Client Credentials, User OAuth, S2S OAuth, Video SDK JWT). 2. Instantiate client(s) with credentials, webhook secret, and per-module port. 3. Register event handlers (webEventConsumer.event(...) or shortcuts). 4. Implement API calls through client.endpoints.*. 5. Start receiver(s) and expose webhook endpoint(s) (/zoom/events) to Zoom. 6. Persist tokens/state for OAuth workloads and enforce signature verification. 7. Monitor module-specific failures and rotate secrets/version with changelog cadence.

High-Level Scenarios

• Team Chat slash-command bot + Team Chat data API enrichment.
• Multi-module backend (Users + Meetings + Team Chat + Phone) sharing one process.
• Video SDK telemetry backend using videosdk module event stream + API surfaces.
• ISV orchestration layer with tenant-aware token storage and per-module webhooks.
• AWS Lambda webhook processor with Rivet AwsLambdaReceiver.

See scenarios/high-level-scenarios.md for details.

Chaining

• OAuth architecture and grant selection: ../oauth/SKILL.md
• API endpoint semantics and request payload details: ../rest-api/SKILL.md
• Team Chat app cards, command and bot UX: ../team-chat/SKILL.md
• Video SDK API-specific behavior and BYOS context: ../video-sdk/SKILL.md

Environment Variables

• See references/environment-variables.md for standardized .env keys and where to find each value.

Operations

• RUNBOOK.md - 5-minute preflight and debugging checklist.

Rivet Architecture and Lifecycle

What Rivet Provides

Rivet wraps three concerns into one module client:

• Auth/token orchestration
• Webhook receiver + event dispatch
• Typed REST API endpoint wrappers

Architecture Model

+--------------------+        +------------------------------+
| Zoom Marketplace   |        | Your Rivet App               |
| App Config         |        | (Node.js/TypeScript)         |
+----------+---------+        +---------------+--------------+
           |                                  |
           | OAuth install / token exchange   |
           |--------------------------------->|
           |                                  |
           | Webhooks (POST /zoom/events)     |
           |--------------------------------->|
           |                                  v
           |                        +------------------------+
           |                        | Rivet Module Clients   |
           |                        | - ChatbotClient        |
           |                        | - TeamChatClient       |
           |                        | - Meetings*Client      |
           |                        | - Users*Client         |
           |                        | - Phone*Client         |
           |                        | - VideoSdkClient       |
           |                        +-----+------------+-----+
           |                              |            |
           |                              |            +--> webEventConsumer
           |                              |
           |                              +--> endpoints.* (REST wrappers)
           |                                           |
           |                                           v
           |                                  +------------------+
           +--------------------------------> | Zoom APIs        |
                                              +------------------+

Lifecycle Workflow

1. Select module(s):

• Example: ChatbotClient + TeamChatClient for bot + channel lookup.
• Example: UsersS2SAuthClient + MeetingsS2SAuthClient for admin automation.

2. Pick auth model by module:

• Chatbot: Client Credentials
• Team Chat/Meetings/Phone/Accounts/Users: User OAuth or S2S OAuth
• Video SDK: JWT auth for Video SDK API

3. Configure client options:

• Required: clientId, clientSecret
• Often required: webhooksSecretToken
• Conditional: accountId, installerOptions, receiver, port, tokenStore

4. Register listeners:

• Generic: webEventConsumer.event("event_name", handler)
• Shortcuts where available: onSlashCommand, onButtonClick, onChannelMessagePosted

5. Start server(s):

• await client.start() returns server handler/address
• For multi-module apps, assign unique ports

6. Wire Marketplace subscriptions:

• Endpoint URL must target each module's receiver port
• Endpoint path should include /zoom/events

7. Process API + events:

• API calls via client.endpoints.*
• Event-driven actions via callback handlers

8. Operate and upgrade:

• Persist OAuth tokens/state for stable restarts
• Use changelog + TypeDoc workflow for version upgrades

Why Multi-Client Port Strategy Matters

In sample patterns, each module runs its own receiver port. If multiple modules share one port by mistake, webhook routing and verification behavior can break in non-obvious ways.

Getting Started Pattern (Single Module)

This pattern shows a minimal Rivet bootstrap for Team Chat with OAuth installation support.

import { TeamChatClient } from "@zoom/rivet/teamchat";

(async () => {
  const teamchatClient = new TeamChatClient({
    clientId: process.env.RIVET_CLIENT_ID,
    clientSecret: process.env.RIVET_CLIENT_SECRET,
    webhooksSecretToken: process.env.RIVET_WEBHOOK_SECRET_TOKEN,
    installerOptions: {
      redirectUri: process.env.RIVET_REDIRECT_URI,
      stateStore: process.env.RIVET_STATE_STORE_SECRET,
    },
    port: Number(process.env.RIVET_PORT || 8080),
  });

  teamchatClient.webEventConsumer.event("chat_message.sent", ({ payload }) => {
    console.log("event", payload);
  });

  const server = await teamchatClient.start();
  console.log("rivet server", server.address());
})();

Required Marketplace Wiring

• Add endpoint URL to event subscription with /zoom/events suffix.
• Ensure OAuth redirect URI exactly matches installerOptions.redirectUri + callback path behavior.
• Include all scopes needed by endpoints.* calls.

Common Extension

Add API calls with typed wrappers:

const channels = await teamchatClient.endpoints.chatChannels.listUsersChannels({
  path: { userId: "me" },
});

Multi-Client Pattern (Two Modules, Two Ports)

Use this when combining chatbot command handling with Team Chat API lookups.

import { ChatbotClient } from "@zoom/rivet/chatbot";
import { TeamChatClient } from "@zoom/rivet/teamchat";

const CHATBOT_PORT = Number(process.env.RIVET_CHATBOT_PORT || 4001);
const TEAMCHAT_PORT = Number(process.env.RIVET_TEAMCHAT_PORT || 4002);

(async () => {
  const chatbotClient = new ChatbotClient({
    clientId: process.env.RIVET_CLIENT_ID,
    clientSecret: process.env.RIVET_CLIENT_SECRET,
    webhooksSecretToken: process.env.RIVET_WEBHOOK_SECRET_TOKEN,
    port: CHATBOT_PORT,
  });

  const teamchatClient = new TeamChatClient({
    clientId: process.env.RIVET_CLIENT_ID,
    clientSecret: process.env.RIVET_CLIENT_SECRET,
    webhooksSecretToken: process.env.RIVET_WEBHOOK_SECRET_TOKEN,
    installerOptions: {
      redirectUri: process.env.RIVET_REDIRECT_URI,
      stateStore: process.env.RIVET_STATE_STORE_SECRET,
    },
    port: TEAMCHAT_PORT,
  });

  chatbotClient.webEventConsumer.onSlashCommand("help", async ({ say }) => {
    await say("Rivet bot ready.");
  });

  chatbotClient.webEventConsumer.onSlashCommand("channels", async ({ say, payload }) => {
    const result = await teamchatClient.endpoints.chatChannels.listUsersChannels({
      path: { userId: payload.userId },
    });

    const names = (result.data?.channels || []).map((x) => x.name).join(", ");
    await say(`Channels: ${names || "none"}`);
  });

  await teamchatClient.start();
  await chatbotClient.start();
})();

Operational Notes

• Subscribe chatbot events to CHATBOT_PORT endpoint.
• Complete Team Chat OAuth install flow against TEAMCHAT_PORT.
• Keep ports unique and explicit in documentation and deployment configs.

Rivet SDK Environment Variables

Standardized .env keys for Rivet-based integrations.

Core Keys

Port Keys

Video SDK-Specific Note

Rivet's videosdk module constructor uses clientId/clientSecret fields, but those map to Video SDK credentials for the app type you configure. Validate with current Video SDK credential model before release.

Example .env

RIVET_CLIENT_ID="..."
RIVET_CLIENT_SECRET="..."
RIVET_WEBHOOK_SECRET_TOKEN="..."
RIVET_ACCOUNT_ID="..."
RIVET_REDIRECT_URI="http://YOUR_DEV_HOST:4002"
RIVET_STATE_STORE_SECRET="replace-me"
RIVET_CHATBOT_PORT=4001
RIVET_TEAMCHAT_PORT=4002

Rivet Reference Map

Canonical Documentation

• Product docs: https://developers.zoom.us/docs/rivet/
• JavaScript docs: https://developers.zoom.us/docs/rivet/javascript/
• TypeDoc reference: https://zoom.github.io/rivet-javascript/modules.html

Modules (TypeDoc)

From @zoom/rivet TypeDoc module index:

• Accounts
• Chatbot
• Meetings
• Phone
• Team Chat
• Users
• Video SDK

Each module generally exposes:

• *Client class(es)
• *Endpoints wrapper class
• *EventProcessor
• HttpReceiver and AwsLambdaReceiver
• Shared option/types/error surfaces

Key API Shapes

• Event subscription:
• client.webEventConsumer.event(eventName, handler)
• Event shortcut examples:
• onSlashCommand, onButtonClick, onChannelMessagePosted
• Endpoint wrappers:
• client.endpoints.<group>.<operation>({ path, query, body })

Important Links for Validation

• Rivet sample app: https://github.com/zoom/rivet-javascript-sample
• ISV starter sample: https://github.com/zoom/isv-rivet-starter
• Rivet server sample: https://github.com/zoom/Rivet-Server-Sample
• Rivet package source: https://github.com/zoom/rivet-javascript

Rivet Sample Validation and Observed Drift

Validated sources:

• zoom/rivet-javascript-sample
• zoom/isv-rivet-starter
• zoom/Rivet-Server-Sample
• zoom/rivet-javascript

Lifecycle Patterns Confirmed

• Module clients are instantiated with auth + receiver options.
• Handlers are registered before or near startup.
• client.start() bootstraps receiver/server.
• Multi-module samples use unique ports per module.
• /zoom/events endpoint suffix is required for webhook callbacks.

Architecture Patterns Confirmed

• Rivet acts as an orchestration layer:
• Typed endpoint wrappers for API operations.
• Webhook consumer methods for events.
• OAuth helper behavior embedded in client lifecycle.

Useful Additions Incorporated into Skill

• Multi-module port segregation and webhook endpoint mapping.
• Distinct auth patterns by module.
• Sample-derived operational gotchas for ngrok and OAuth install.

Contradictions and Drift Notes

• Some docs/samples reference older Team Chat doc paths (team-chat-apps) while current docs may use updated routing.
• Sample env variable naming is inconsistent across repos (StS_*, WEBHOOK_SECRET_TOKEN, per-module keys). This skill standardizes names in environment-variables.md.
• Some sample README commands imply one port while module receivers may actually use base+1 or per-module ports.
• User OAuth behavior depends on receiver choice; AwsLambdaReceiver limitations must be handled explicitly.

Recommendations

• Keep a local compatibility table: rivet_version x modules_used x auth_flows x receiver_type.
• Treat sample repos as patterns, not strict source of truth.
• Re-check TypeDoc and changelog before each release.

Rivet Source Map

Crawled Docs (local raw-docs)

• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/get-started.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/authorization.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/apis-events.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/config-options.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/deployment.md
• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/javascript/event-shortcuts.md
• tools/zoom-crawler/raw-docs/zoom.github.io/rivet-javascript/ (TypeDoc crawl)

External Validation Repos

• zoom/rivet-javascript-sample
• zoom/isv-rivet-starter
• zoom/Rivet-Server-Sample
• zoom/rivet-javascript

Rivet Versioning and Compatibility

Upgrade Strategy

Use the standard upgrade workflow:

• ../../general/references/sdk-upgrade-workflow.md

For Rivet, treat upgrades as three parallel checks: 1. @zoom/rivet package release changes 2. Underlying Zoom API/event payload changes 3. Marketplace app config and scope changes

Compatibility Risks

• Module/auth behavior drift across versions.
• Type alias or endpoint wrapper signature changes.
• Event payload shape differences for webhook types.
• Receiver behavior changes in Node runtime/Lambda environments.

Version Signals

• @zoom/rivet package version in package.json.
• TypeDoc module/classes/type aliases under zoom.github.io/rivet-javascript.
• Changelog updates under https://developers.zoom.us/changelog/.

Safe Upgrade Checklist

• Pin current and target @zoom/rivet versions.
• Compare TypeDoc module pages for changed constructor options and endpoints.
• Validate event names and payload fields used by your handlers.
• Revalidate OAuth install/callback flow and token persistence.
• Revalidate per-module port and /zoom/events mapping.

Zoom Rivet SDK (Overview)

Rivet is a server-side framework for Zoom integrations in JavaScript/TypeScript.

For full documentation and navigation, start at SKILL.md.

Quick Links

• Architecture and Lifecycle
• High-Level Scenarios
• Getting Started Pattern
• Multi-Client Pattern
• Reference Map
• Sample Validation
• Common Issues

Rivet SDK 5-Minute Preflight Runbook

Use this before deep debugging.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SDK/API names can drift by version; validate names against changelog and TypeDoc before release.

1) Confirm Integration Surface

• Confirm this is a server-side Node.js integration path using @zoom/rivet.
• Confirm module boundaries (Chatbot, Team Chat, Meetings, Phone, Accounts, Users, Video SDK).
• Confirm whether the app needs event receiver mode, API-only mode, or both.

2) Confirm Required Credentials

• clientId, clientSecret for each module auth flow.
• webhooksSecretToken for webhook verification (required for receiver flows).
• accountId for S2S modules.
• redirectUri and stateStore for User OAuth modules.

3) Confirm Lifecycle Order

1. Instantiate module client(s) with auth/receiver options. 2. Register webhook listeners before traffic. 3. Start client server(s) and note per-module port(s). 4. Expose /zoom/events for each active receiver endpoint. 5. Execute API calls through client.endpoints.*.

4) Confirm Event/State Handling

• Match event names exactly (bot_notification, interactive_message_fields_editable, etc.).
• Keep module-specific webhook endpoints aligned with Marketplace subscription settings.
• Persist OAuth tokens/state for long-lived integrations.
• Keep idempotency in event handlers for retries/duplicates.

5) Confirm Cleanup + Upgrade Posture

• Revalidate all module constructors and options on each upgrade.
• Keep compatibility shims when module/type names change.
• Review changelog version-by-version from current deployment to target.

6) Quick Probes

• Client starts and binds to expected port(s).
• Webhook verification succeeds for subscribed events.
• One API call and one event callback complete successfully for each active module.
• User OAuth install/callback flow works end-to-end when applicable.

7) Fast Decision Tree

• API works but events fail -> wrong endpoint URL/port/path (/zoom/events) or bad webhook token.
• OAuth install fails -> redirect URI/state store mismatch or unsupported receiver mode.
• Multi-module collisions -> duplicate ports or shared env keys incorrectly mapped.
• Lambda flow issues -> receiver type mismatch or missing webhooksSecretToken.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/rivet/
• https://developers.zoom.us/docs/rivet/javascript/
• https://zoom.github.io/rivet-javascript/

Raw docs in repo

• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/rivet/
• tools/zoom-crawler/raw-docs/zoom.github.io/rivet-javascript/

Rivet High-Level Scenarios

1) Team Chat Standup Bot with Channel Intelligence

• Modules: ChatbotClient + TeamChatClient
• Auth: Client Credentials (chatbot) + User OAuth or S2S for Team Chat APIs
• Flow:

1. Slash command enters chatbot webhook. 2. Bot queries channel and member lists via Team Chat endpoints. 3. Bot posts/updates interactive message cards.

• Risks:
• Misaligned scopes cause endpoint failures.
• Wrong port in Marketplace event subscription prevents callbacks.

2) ISV Admin Automation Service

• Modules: UsersS2SAuthClient, MeetingsS2SAuthClient, optionally AccountsS2SAuthClient
• Auth: S2S OAuth
• Flow:

1. Backend receives internal request to create/update Zoom resources. 2. Rivet endpoints wrap REST calls. 3. Webhooks confirm completion state.

• Risks:
• Missing accountId or stale S2S credentials.
• Event and API schema mismatch across versions.

3) Video SDK API Operations and Recording Workflow

• Module: VideoSdkClient
• Auth: Video SDK JWT
• Flow:

1. Create/list/manage sessions. 2. Manage recording/BYOS/report endpoints. 3. React to session/recording webhooks.

• Risks:
• Wrong credential type (OAuth client vs Video SDK key/secret).
• Ignoring recording and BYOS endpoint field changes after upgrades.

4) AWS Lambda Event Receiver Deployment

• Module: product-specific client + AwsLambdaReceiver
• Flow:

1. Instantiate client with receiver: new AwsLambdaReceiver(...). 2. Export Lambda handler that delegates to await client.start() handler. 3. Use API Gateway/serverless-offline for local parity.

• Risks:
• User OAuth expectations with unsupported receiver flow.
• Secret token mismatch across Lambda environments.

5) Multi-Tenant Event Router

• Modules: one or more, with external token/state stores
• Flow:

1. Receive webhook. 2. Resolve tenant and token context. 3. Execute routed API action. 4. Persist audit and retry state.

• Risks:
• In-memory token store only (tokens lost on restart).
• Missing idempotency for retried webhook events.

Rivet Common Issues

Webhooks never reach handlers

Symptoms:

• client.start() succeeds, but no event callbacks fire.

Checks:

• Marketplace endpoint URL points to correct module port.
• Endpoint includes /zoom/events suffix.
• webhooksSecretToken matches app configuration.
• Ngrok forward is active and mapped to the receiver port.

OAuth install/callback fails

Symptoms:

• Install page redirects fail or callback errors.

Checks:

• installerOptions.redirectUri exactly matches Marketplace OAuth redirect.
• stateStore value is configured and stable.
• Receiver mode supports User OAuth (Lambda receiver caveat).

Multi-module runtime conflicts

Symptoms:

• One module works, another silently fails.

Checks:

• Every module uses a unique port.
• Event subscriptions target the correct module endpoint.
• Env variables are not accidentally shared with wrong module.

API-only mode confusion

Symptoms:

• OAuth expectations fail when receiver disabled.

Checks:

• disableReceiver: true disables OAuth flow behavior.
• For OAuth + API-only behavior, use receiver-compatible configuration and relax webhook verification as documented.

Sample parity mismatches

Symptoms:

• Following sample exactly still fails in your environment.

Checks:

• Normalize env key names to your project standard.
• Reconcile sample README assumptions with current TypeDoc signatures.
• Verify module auth type alignment (Client Credentials vs User OAuth vs S2S).