Setup Zoom Websockets
OpenAIOfficialCreated by ZoomDistributed by OpenAI
- Skill
- Tool integration
- Automation and integrations
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a structured approach to integrating Zoom WebSockets for real-time event streaming. It covers the full connection lifecycle, including Server-to-Server OAuth authentication, token management, heartbeat implementation, and reconnection strategies. It is intended for developers who require persistent event delivery rather than standard HTTP webhook callbacks.
What it does
- Provides steps for configuring Zoom event subscriptions for WebSockets.
- Details the authentication flow using Server-to-Server OAuth tokens.
- Outlines implementation patterns for connection heartbeats and keep-alive pings.
- Defines strategies for handling disconnections and implementing exponential backoff.
- Lists required environment variables for managing Zoom app credentials and subscription IDs.
- Offers guidance on observability and debugging common connection issues.
When to use it
- When your application requires persistent event delivery from Zoom.
- When you need to manage real-time event streams outside of standard HTTP webhook patterns.
- When building custom integration logic that requires manual connection state management.
Advantages
- Provides a clear lifecycle model for managing persistent WebSocket connections.
- Includes code patterns for token refresh and heartbeat maintenance.
- Centralizes configuration requirements for Zoom OAuth and subscription IDs.
- Offers a structured approach to troubleshooting connection and authentication failures.
Usage examples
- “How do I authenticate a Zoom WebSocket connection?”
- The skill explains how to generate a Server-to-Server OAuth access token using your account ID, client ID, and client secret to authorize the WebSocket connection.
- “How can I keep my Zoom WebSocket connection alive?”
- The skill provides a heartbeat implementation pattern using periodic ping/pong messages to maintain the connection state.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/openai/setup-zoom-websockets/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip setup-zoom-websockets.zip -d .agents/skills
Documentation by Zoom
Setup Zoom WebSockets
Use this skill when the integration needs persistent Zoom event delivery instead of HTTP webhook callbacks. If normal webhook retries and delivery are enough, prefer setup-zoom-webhooks.
Workflow
Confirm WebSockets are justified by latency, firewall, connection model, or deployment constraints.
Configure the app and event subscriptions for the required event stream.
Implement connection setup, authentication, heartbeat, reconnect, backoff, and shutdown handling.
Normalize events into the same internal contract used by webhook handlers when both are supported.
Add observability for connection state, reconnect count, event lag, and dropped messages.
Debug by isolating token/auth problems, app subscription settings, network proxies, TLS interception, and reconnect loops.
References
Full preserved guide: references/full-guide.md
Connection: references/connection.md
Events: references/events.md
Common issues: troubleshooting/common-issues.md
Files
- ATTRIBUTION.mdAdded by AutoGineer878 B
- LICENSELicence file added by AutoGineer1.1 KiB
- RUNBOOK.md2.9 KiB
- SKILL.md1.2 KiB
- agents/openai.yaml148 B
- references/connection.md10.2 KiB
- references/environment-variables.md827 B
- references/events.md10.5 KiB
- references/full-guide.md7.0 KiB
- troubleshooting/common-issues.md1.1 KiB
references/full-guide.md
/setup-zoom-websockets
Background reference for persistent Zoom event streams. Prefer workflow routing first, then use this file when WebSockets are plausibly better than webhooks.
WebSockets vs Webhooks
| Aspect | WebSockets | Webhooks |
|---|---|---|
| Connection | Persistent, bidirectional | One-time HTTP POST |
| Latency | Lower (no HTTP overhead) | Higher (new connection per event) |
| Security | Direct connection, no exposed endpoint | Requires endpoint validation, IP whitelisting |
| Model | Pull (you connect to Zoom) | Push (Zoom connects to you) |
| State | Stateful (maintains connection) | Stateless (each event independent) |
| Setup | More complex (access token, connection) | Simpler (just endpoint URL) |
Choose WebSockets when:
Real-time, low-latency updates are critical
Security is paramount (banking, healthcare, finance)
You don't want to expose a public endpoint
You need bidirectional communication
Choose Webhooks when:
Simpler setup is preferred
Small number of event notifications
Existing HTTP infrastructure
Prerequisites
Server-to-Server OAuth app in Zoom Marketplace
Account ID, Client ID, and Client Secret
WebSocket subscription with events enabled
Need help with S2S OAuth? See the zoom-oauth skill for complete authentication flows.
Start troubleshooting fast: Use the 5-Minute Runbook before deep debugging.
Quick Start
1. Create Server-to-Server OAuth App
Go to Zoom Marketplace
Create a Server-to-Server OAuth app
Copy Account ID, Client ID, Client Secret
2. Enable WebSocket Subscription
In your app, go to Feature → Event Subscriptions
Add an Event Subscription
Select WebSockets as the method type
Select events to subscribe to (e.g.,
meeting.created,meeting.started)Save - an endpoint URL will be generated
3. Connect via WebSocket
const WebSocket = require('ws');
const axios = require('axios');
// Step 1: Get access token
async function getAccessToken() {
const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
const response = await axios.post(
'https://zoom.us/oauth/token',
new URLSearchParams({
grant_type: 'account_credentials',
account_id: ACCOUNT_ID
}),
{
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/x-www-form-urlencoded'
}
}
);
return response.data.access_token;
}
// Step 2: Connect to WebSocket
async function connectWebSocket() {
const accessToken = await getAccessToken();
// WebSocket URL from your subscription settings
const wsUrl = `wss://ws.zoom.us/ws?subscriptionId=${SUBSCRIPTION_ID}&access_token=${accessToken}`;
const ws = new WebSocket(wsUrl);
ws.on('open', () => {
console.log('WebSocket connection established');
});
ws.on('message', (data) => {
const event = JSON.parse(data);
console.log('Event received:', event.event);
// Handle different event types
switch (event.event) {
case 'meeting.started':
console.log(`Meeting started: ${event.payload.object.topic}`);
break;
case 'meeting.ended':
console.log(`Meeting ended: ${event.payload.object.uuid}`);
break;
case 'meeting.participant_joined':
console.log(`Participant joined: ${event.payload.object.participant.user_name}`);
break;
}
});
ws.on('close', (code, reason) => {
console.log(`Connection closed: ${code} - ${reason}`);
// Implement reconnection logic
});
ws.on('error', (error) => {
console.error('WebSocket error:', error);
});
return ws;
}
connectWebSocket();Event Format
Events received via WebSocket have the same format as webhook events:
{
"event": "meeting.started",
"event_ts": 1706123456789,
"payload": {
"account_id": "abcD3ojkdbjfg",
"object": {
"id": 1234567890,
"uuid": "abcdefgh-1234-5678-abcd-1234567890ab",
"host_id": "xyz789",
"topic": "Team Standup",
"type": 2,
"start_time": "2024-01-25T10:00:00Z",
"timezone": "America/Los_Angeles"
}
}
}Common Events
| Event | Description |
|---|---|
meeting.created | Meeting scheduled |
meeting.updated | Meeting settings changed |
meeting.deleted | Meeting deleted |
meeting.started | Meeting begins |
meeting.ended | Meeting ends |
meeting.participant_joined | Participant joins meeting |
meeting.participant_left | Participant leaves meeting |
recording.completed | Cloud recording ready |
user.created | New user added |
user.updated | User details changed |
Connection Management
Keep-Alive
WebSocket connections require periodic heartbeats. Zoom will close idle connections.
// Send ping every 30 seconds
setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.ping();
}
}, 30000);Reconnection
Implement automatic reconnection for reliability:
function connectWithReconnect() {
const ws = connectWebSocket();
ws.on('close', () => {
console.log('Connection lost. Reconnecting in 5 seconds...');
setTimeout(connectWithReconnect, 5000);
});
return ws;
}Single Connection Limit
Important: Only ONE WebSocket connection can be open per subscription at a time. Opening a new connection will close the existing one.
Detailed References
references/connection.md - Connection lifecycle, authentication, error handling
references/events.md - Complete event types reference
Troubleshooting
troubleshooting/common-issues.md - Subscription URL confusion, disconnects, no-events debugging
Sample Repositories
Official / Community
| Type | Repository | Description |
|---|---|---|
| Node.js | just-zoomit/zoom-websockets | WebSocket sample with S2S OAuth |
WebSockets vs RTMS
Don't confuse WebSockets with RTMS (Realtime Media Streams):
| Feature | WebSockets | RTMS |
|---|---|---|
| Purpose | Event notifications | Media streams |
| Data | Meeting events, user events | Audio, video, transcripts |
| Use case | React to Zoom events | AI/ML, live transcription |
| Skill | This skill | rtms |
For real-time audio/video/transcript data, use the rtms skill instead.
Resources
WebSockets docs: https://developers.zoom.us/docs/api/websockets/
Webhooks comparison: https://www.zoom.com/en/blog/a-guide-to-webhooks-and-websockets/
Developer forum: https://devforum.zoom.us/
Environment Variables
See references/environment-variables.md for standardized
.envkeys and where to find each value.
Requirements and compatibility
Written for: OpenAI Codex
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- Zoom
- Publisher
- OpenAI (Official)
- Distributed by
- OpenAI
- Source
- openai/plugins · plugins/zoom/skills/websockets · commit d420d13
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from plugins/zoom/LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Zoom or OpenAI.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download setup-zoom-websockets.zip