Zoom Rtms

Common Issues

Troubleshooting guide for Zoom RTMS.

Quick Diagnostics

Connection Issues

Webhook Response Timing

Problem: Random disconnections, duplicate connections

Cause: If your webhook handler takes too long to respond, Zoom retries. The retry creates a second connection, which kicks out the first (only 1 connection allowed per stream).

Solution: Respond 200 IMMEDIATELY before any processing:

// CORRECT
app.post('/webhook', (req, res) => {
  res.status(200).send();  // FIRST!

  // Then process asynchronously
  setImmediate(() => {
    handleRTMSEvent(req.body);
  });
});

// WRONG
app.post('/webhook', async (req, res) => {
  await heavyProcessing(req.body);  // Zoom retries while waiting!
  res.status(200).send();
});

Duplicate Connection Prevention

Problem: Multiple connections to same stream

Solution: Track active sessions:

const activeSessions = new Map();

function handleRTMSStarted(payload) {
  const streamId = payload.rtms_stream_id;

  if (activeSessions.has(streamId)) {
    console.log('Already connected, ignoring duplicate');
    return;
  }

  activeSessions.set(streamId, Date.now());
  connectToRTMS(payload);
}

function handleRTMSStopped(payload) {
  activeSessions.delete(payload.rtms_stream_id);
}

Invalid Signature

Problem: Handshake fails with status_code 3

Cause: Signature generation incorrect

Solution: Verify format:

// Message format: "clientId,meetingUuid,streamId"
const message = `${clientId},${meetingUuid},${streamId}`;
const signature = crypto.createHmac('sha256', clientSecret)
  .update(message)
  .digest('hex');

Checklist:

• [ ] Using correct clientId (not app name)

• [ ] Using correct clientSecret

• [ ] No extra spaces in message

• [ ] Using hex output (not base64)

Connection Timeout

Problem: WebSocket connection times out

Causes:

• Network issues

• Firewall blocking WebSocket

• Server URL expired

Solution:

1. Check network connectivity

2. Ensure firewall allows WSS

3. Use fresh webhook payload (don't cache URLs)

Heartbeat Issues

Connection Closes Unexpectedly

Problem: Connection closes after ~60 seconds

Cause: Not responding to heartbeat

Solution: Respond to msg_type 12 with msg_type 13:

ws.on('message', (data) => {
  const msg = JSON.parse(data);

  if (msg.msg_type === 12) {
    ws.send(JSON.stringify({
      msg_type: 13,
      timestamp: msg.timestamp
    }));
  }
});

Timeouts:

• Signaling: ~60 seconds

• Media: ~65 seconds

Media Data Issues

No Audio Data

Causes:

1. Wrong media_type in handshake

2. No participants speaking

3. Audio not enabled in meeting

Solution:

1. Verify media_type includes AUDIO (1):

   Copy

   media_type: 1  // Just audio
   media_type: 9  // Audio + Transcript
   media_type: 32 // All media

2. Wait for participant to speak

3. Check meeting audio settings

No Video Data

Causes:

1. Wrong media_type

2. No video enabled

3. Wrong codec for FPS

4. Individual video mode enabled but no participant subscription sent

Solution:

1. Include VIDEO (2) in media_type

2. Use H.264 for fps > 5:

   Copy

   video: {
     codec: 7,        // H.264
     resolution: 2,   // HD
     fps: 25          // > 5 requires H.264
   }

3. If using VIDEO_SINGLE_INDIVIDUAL_STREAM, also:

   • subscribe to PARTICIPANT_VIDEO_ON / PARTICIPANT_VIDEO_OFF

   • send VIDEO_SUBSCRIPTION_REQ with a live user_id

   • remember a new request replaces the previous participant stream

No Screen Share Data

Problem: Not receiving screen share even when active

Cause: Screen share is SEPARATE from video

Solution: Include DESKSHARE (4) in media_type:

media_type: 4   // Just screen share
media_type: 5   // Audio + screen share
media_type: 32  // All media

Transcript Language Delay

Problem: noticeable startup delay before transcription stabilizes

Cause: Language Identification (LID) is enabled and RTMS is auto-detecting / auto-switching languages

Solution: Set a source language and disable LID when you want a fixed language:

transcript: {
  content_type: 5,
  src_language: 9,   // English
  enable_lid: false  // Fixed language, no auto-switch
}

Language IDs:

See Data Types for full list.

Participant Video Events Arrive But No Video Stream Follows

Problem: You receive PARTICIPANT_VIDEO_ON, but no actual participant video frames arrive.

Cause: Those events only tell you whose camera is currently available. They do not automatically switch the data socket to that participant.

Solution:

1. open the video media socket with VIDEO_SINGLE_INDIVIDUAL_STREAM

2. handle PARTICIPANT_VIDEO_ON / PARTICIPANT_VIDEO_OFF

3. choose one user_id

4. send VIDEO_SUBSCRIPTION_REQ

5. wait for VIDEO_SUBSCRIPTION_RESP

Also remember:

• only one participant stream is supported at a time

• a newer subscription overrides the previous participant stream

Stream Never Closes Cleanly From Backend

Problem: Your app finishes processing, but the RTMS stream remains open until external stop events arrive.

Solution: Use the new graceful-close control message on the signaling socket:

signalingWs.send(JSON.stringify({
  msg_type: 21, // STREAM_CLOSE_REQ
  rtms_stream_id: streamId
}));

Treat STREAM_CLOSE_RESP as acknowledgement, then continue with local cleanup.

SDK-Specific Issues

Segmentation Fault

Problem: App crashes with segmentation fault

Cause: Node.js version < 20.3.0

Solution:

# Check version
node --version

# Upgrade with nvm
nvm install 24
nvm use 24

# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Audio Metadata Missing userId

Problem: onAudioData metadata doesn't include speaker userId

Cause: Using AUDIO_MIXED_STREAM (all audio combined)

Solution: Use onActiveSpeakerEvent for speaker identification:

client.onActiveSpeakerEvent((timestamp, userId, userName) => {
  console.log(`Current speaker: ${userName}`);
});

Or use AUDIO_MULTI_STREAMS:

client.setAudioParams({
  dataOpt: 2  // Per-participant streams
});

Video Parameters Ignored

Problem: setVideoParams not taking effect

Cause: SDK bug - video params ignored after audio params

Workaround: Call setVideoParams BEFORE setAudioParams:

// CORRECT ORDER
client.setVideoParams({ codec: 7, fps: 25 });
client.setAudioParams({ codec: 4, sampleRate: 3 });
client.join(payload);

SDK Invalid State

Problem: "Invalid status" error on join

Cause: SDK still cleaning up from previous session

Solution: Retry with delay:

try {
  client.join(payload);
} catch (error) {
  if (error.message?.includes('Invalid status')) {
    console.warn('SDK cleaning up, retrying in 2s');

    setTimeout(() => {
      client.join(payload);
    }, 2000);
  }
}

Platform Issues

Platform Not Supported

Problem: SDK installation fails

Currently Supported:

• darwin-arm64 (Apple Silicon)

• linux-x64

Not Yet Supported:

• Windows

• darwin-x64 (Intel Mac)

• linux-arm64

Workaround: Use Manual WebSocket implementation.

Status Code Reference

See Data Types for complete list.

Product-Specific Issues

Video SDK Issues

Problem: Signature validation fails for Video SDK sessions

Cause: Using OAuth Client ID/Secret instead of SDK Key/Secret, or using meeting_uuid instead of session_id.

Solution:

• Video SDK apps use SDK Key (as clientId) and SDK Secret (as clientSecret).

• Video SDK webhook payloads contain session_id, NOT meeting_uuid.

• The HMAC signature must use session_id: HMAC-SHA256(sdkSecret, "sdkKey,sessionId,streamId")

// Extract the correct ID based on product
const idValue = payload.meeting_uuid || payload.session_id;
const signature = generateSignature(clientId, idValue, streamId, clientSecret);

Webinar Issues

Problem: Looking for webinar_uuid in the payload

Cause: Expecting a webinar-specific UUID field.

Solution: Webinar RTMS payloads still use meeting_uuid (NOT webinar_uuid). This is a common gotcha. The signature, connection flow, and protocol are identical to meetings.

Problem: Missing attendee streams in webinars

Cause: Webinar attendees are view-only participants.

Solution: Only panelist audio/video streams are confirmed to be available via RTMS. Attendee streams may not be available individually. Design your application to work with panelist streams only.

Problem: Practice session not triggering RTMS

Cause: Practice sessions are not documented for RTMS support.

Solution: RTMS events are expected when the webinar goes live to attendees, not during practice sessions. Q&A and Polls data are also not exposed via RTMS.

Getting Help

1. Developer Forum: https://devforum.zoom.us/

2. GitHub Issues: https://github.com/zoom/rtms/issues

3. Official Docs: https://developers.zoom.us/docs/rtms/

Next Steps

• Connection Architecture - Understand the protocol

• Lifecycle Flow - Correct connection sequence

• Data Types - All status codes and enums