Web Call Join Failures & Microphone Permissions

Overview

When a customer starts a web call, their browser must complete a short handshake with the core system before the conversation can begin. If that handshake doesn't finish within a configurable timeout window, the call ends automatically — usually surfacing as a failed or silent-sounding call. This page explains why that happens and how to configure the timeout so real users have enough time to join.

Before a web call can start, the customer's browser must complete three steps within the timeout window:

• Network Connection — the browser establishes a connection to the core system's servers.
• Microphone Permission — the browser prompts the user to grant microphone access, and the user must respond.
• WebRTC Handshake — the audio connection completes negotiation.

If all three steps don't finish before the timeout expires, the call ends with an error indicating the assistant never received any customer audio.

The join timeout is controlled by customerJoinTimeoutSeconds, which defaults to 15 seconds and can be set anywhere from 1 to 60 seconds. In practice, 15 seconds is frequently not enough. A realistic breakdown for a first-time user looks like this:

At the default 15-second timeout, this call would fail even though the user was actively trying to join — they simply hadn't finished responding to the permission prompt yet.

Because join time varies by device, network, and familiarity with the flow, set customerJoinTimeoutSeconds based on who's actually joining:

If you're unsure which segment applies, start conservatively (30–60 seconds) and tighten the value once you've reviewed your own join success rates.

You can set customerJoinTimeoutSeconds on the assistant itself, or override it for an individual call.

On assistant creation:

{
  "name": "Customer Support Assistant",
  "model": { "provider": "openai", "model": "gpt-4.1-mini" },
  "voice": { "provider": "11labs", "voiceId": "21m00Tcm4TlvDq8ikWAM" },
  "customerJoinTimeoutSeconds": 30
}

Per-call override (without changing the assistant itself):

{
  "assistantId": "your-assistant-id",
  "assistantOverrides": {
    "customerJoinTimeoutSeconds": 60
  }
}

Note that this setting applies only to web calls — phone calls are not affected.

A few practical steps reduce join failures beyond simply raising the timeout:

• Set expectations before the call starts — tell users they'll be asked for microphone access and why, so they respond to the browser prompt faster.
• Show a loading indicator — display connection/status feedback while the join process runs, so users don't assume the page is frozen and close the tab.
• Handle the widget's error event for microphone-denied cases so you can show a clear, actionable message instead of a silent failure.
• Require HTTPS — browsers block microphone access on insecure (non-HTTPS) origins, so any page hosting a web call widget must be served over HTTPS or the permission step will fail every time.

Example error-event handler:

document.addEventListener('DOMContentLoaded', function() {
  const widget = document.querySelector('sulus-widget');

  widget.addEventListener('error', function(event) {
    const error = event.detail;

    if (error.message.includes('microphone')) {
      alert('Please allow microphone access to use voice features.');
    } else if (error.message.includes('network')) {
      alert('Connection error. Please check your internet connection.');
    } else {
      alert('Something went wrong. Please try again.');
    }
  });
});