Pre-Call Testing Best Practices

This guide describes a pre-call experience for Video API applications that want to reduce join failures and protect the live session experience. It covers waiting rooms, permissions and device setup, network testing, result interpretation, and the join decision.

A pre-call test estimates call quality at one point in time. It can catch setup issues before the session starts, but it cannot predict what will happen later in the call. Keep monitoring after the user joins with Client Observability, quality events, and runtime adaptation features.

Recommended Pre-Call Flow

1. Use a waiting room before the user joins the call.
2. Check camera and microphone permissions and show local preview.
3. Let the user choose devices and show which camera and microphone are currently selected.
4. Run the pre-call test with separate test credentials and a separate test session. This keeps the call session and its Inspector data separate from test connections and streams.
5. Run NetworkTest.testConnectivity() first, then NetworkTest.testQuality().
6. Use the documented outputs to set a waiting-room status. A simple model is Pass, Warn, or Fail.
7. Join the session after permissions, device setup, and pre-call checks are complete. For Warn, one option is to let the user continue with a clear warning.

If you use the network-test library, create a separate routed test session. Do not reuse the communication session ID for the test session. If the test implementation accepts explicit audioSource and videoSource values, use the camera and microphone selected in the waiting room.

Waiting Rooms

A waiting room gives users time to check camera and microphone permissions and choose devices before they enter the call. Use it to apply recommended publish settings and run a pre-call test before the session starts. This keeps setup separate from the live session and helps reduce early disruptions when participants join. The Web Reference App includes a waiting room for previewing devices and handling setup before join.

Waiting Room UI

The waiting room can include the following:

• Local camera preview,
• Microphone activity indicator,
• Camera and microphone selectors,
• Clear permission state and denied-state messaging,
• Pre-call test status or progress indicator,
• A visible join readiness state,
• A retry action for the pre-call test.

Run the test again when any of the following happens:

• The user changes the camera or microphone,
• The user's network changes,
• Camera or microphone permission is granted again after being denied,
• The user explicitly asks to retry,
• Significant time passes between test completion and join.

Host or Moderator Patterns

If your product has a host, moderator, or presenter role, participants can remain in the waiting room until the host is ready to start the live session. In some small-group or moderated applications, participants may instead join the session before the host publishes and remain connected but non-publishing until the host is ready. Treat that connected but non-publishing approach as an optional application-level pattern with scale tradeoffs, not a general recommendation or Video API platform requirement. For larger audiences, pre-connecting many participants can create a burst of subscriptions when the host starts publishing. The waiting-room sample app article shows one example implementation.

Run Network Tests

Use the Vonage Video Network test library to check whether a client can support publishing audio and video before users join a session.

If your application uses configurable TURN or IP proxy settings, pass the corresponding iceConfig or proxyServerUrl values into the network test as well.

Connectivity Checks

Run NetworkTest.testConnectivity() before the quality test.

This check verifies whether the client can reach the services required for a Video API session:

• API reachability,
• Messaging / signaling WebSocket reachability,
• Media-router reachability,
• Logging-server reachability.

Interpret these results based on the session mode your application uses:

• If the api or messaging check fails, the client cannot establish the required session connections.
• If the media check fails, a routed session will not succeed. A relayed session may still succeed, although it can still fail if TURN is needed.
• If the logging check fails, the client may still connect, but Vonage will not collect the usual logging data used by tools such as Inspector.

Quality Checks

If the connectivity results are acceptable for your use case, run NetworkTest.testQuality()to test:

• Audio support,
• Video support,
• Audio and video bitrate,
• Audio and video packet-loss ratio,
• Recommended publish resolution,
• Recommended publish frame rate,
• qualityLimitationReason with values bandwidth, cpu, or null.

Timeout Tests

The timeout option for testQuality() accepts values greater than 5000 ms and less than 30000 ms. If you do not set it, the test runs for approximately:

• 30 seconds for an audio-video test,
• 10 seconds for an audio-only test.

Lower timeouts reduce result accuracy.

Browser Support

testQuality() is not supported in Firefox. In that case, use the waiting room for permissions and device setup, and rely on testConnectivity() if you still want a connectivity-only pre-call check.

Restricted Networks

On restricted networks, follow the documented network requirements:

• Prefer an environment where UDP 3478 and TCP 443 are available.
• For the best setup time and media quality, also allow outbound UDP 1025-65535 for media ICE and SRTP.
• If only TCP 443 is available, the session may still connect, but slower setup and lower media quality are more likely.
• If a proxy is present, it should be transparent or configured for HTTPS connections.

On corporate or restricted networks, verify the same required ports and protocols, then rerun the connectivity test before the user joins.

For more restrictive environments, see:

• Restricted Network Guidelines
• Configurable TURN Servers
• IP Proxy Routing

Recommended Pre-Call Statuses

When the status is Warn or Fail, use the signal that triggered it to decide what to do next:

• If the issue is bandwidth, ask the user to retry on a stronger or less restricted network, or continue with reduced publish settings.
• If the issue is cpu, ask the user to close demanding applications, disable expensive effects, and retry.
• If the issue is logging only, the user may still connect, but normal Inspector data will be reduced.
• If the browser is Firefox, use the waiting room for permissions and device setup, and use testConnectivity() if you need a connectivity-only pre-call check.

Interpreting Network Test Results

When setting a pre-call status, check:

• Support vs. not-supported,
• Connectivity outcome,
• Packet-loss ratio (below 3% is acceptable; 3–5% warrants caution; above 5% indicates failure),
• Bitrate levels (video ≥150 kbps and audio ≥25 kbps are minimum acceptable thresholds),
• Recommended publish resolution and frame rate,
• qualityLimitationReason.

If you need lower-level diagnostics such as round-trip time, freeze counts, or raw RTC statistics, use Client Observability or the raw WebRTC stats report.

In-Call Quality Signals

After the user joins:

• Use qualityScoreChanged to track subscriber quality on the in-call integer 1-5 scale,
• Use cpuPerformanceChanged to react to device pressure in web clients,
• Use publisher and subscriber quality events from Client Observability when you need more detail than basic pre-call checks provide.

For detailed web guidance, see Client Observability: Web.

Continue After Join

After the user joins, continue with:

• Client Observability for ongoing stream metrics,
• Subscribe: Quality & Adaptation for subscriber quality monitoring and reconnection handling,
• Scalable Video for multi-party stream adaptation,
• Audio Fallback for degraded-network behavior,
• Sessions to align your pre-call logic with routed vs. relayed behavior,
• Session Inspector for post-call validation and debugging.

Subscriber audio fallback requires a routed session. Publisher audio fallback is available in both routed and relayed sessions.