Introduction

When a realtime sales avatar “drops,” the failure is rarely in one place. The symptom usually looks simple in the browser: the video freezes, audio continues for a bit, then the WebRTC connection tears down or the avatar stops responding. Underneath that, you may be dealing with a signaling timeout, an ICE restart that never completes, a track negotiation bug, a server-side session expiry, or a client-side lifecycle issue in your own app.

This post walks through a practical debugging approach for WebRTC session drops in a JavaScript realtime avatar integration. By the end, you should be able to narrow a failure to one of the common layers, inspect the right signals in browser and server logs, and harden your app so transient network issues do not kill the session unnecessarily.

Start by separating signaling, media, and application state

With WebRTC, “the connection” is not one thing. In practice, you have three states that can fail independently:

• Signaling: your app exchanges SDP offers/answers and ICE candidates over HTTP, WebSocket, or some API-backed control plane.

• Media transport: ICE, DTLS, and SRTP move audio/video packets once peers connect.

• Application state: your voice agent, avatar session, token, or room membership can expire even while the browser still has a live peer connection.

Debugging gets easier when you stop treating “session drop” as a single event. First ask: did the browser lose the peer connection, or did the backend decide the realtime session was over?

What to inspect in the browser

For browser-side debugging, the two most useful tools are RTCPeerConnection state transitions and getStats(). If you only log the UI state, you will miss most of the interesting failure modes.

Log these transitions explicitly:

pc.onconnectionstatechange = () => {

};

pc.onconnectionstatechange = () => {

};

pc.onconnectionstatechange = () => {

};

The distinction matters:

• connecting followed by failed usually points to ICE connectivity or NAT traversal.

• connected followed by disconnected often means a transient network interruption.

• connected with audio continuing but video freezing can be a track-level or bandwidth issue, not a full peer loss.

Then inspect stats. A good minimal loop is to sample once every few seconds when the call is active:

async function dumpStats(pc) {
}

async function dumpStats(pc) {
}

async function dumpStats(pc) {
}

Useful patterns:

• Rising packetsLost plus higher RTT usually means network degradation.

• availableOutgoingBitrate collapsing before the drop suggests congestion, often on the client uplink or an over-aggressive encoder profile.

• No candidate pair ever becomes nominated usually means ICE never found a viable route, often due to firewall or TURN configuration.

Check lifecycle bugs before blaming WebRTC

A large fraction of “random” drops are actually application lifecycle bugs. In a sales agent UI, the WebRTC session is often tied to a React component, route, modal, or tab state. If that component unmounts and recreates the peer connection, the connection will look flaky even when networking is fine.

Common mistakes:

• Creating a new RTCPeerConnection on every render or state change.

• Calling close() during a rerender because cleanup logic is too aggressive.

• Reusing stale auth/session metadata after the server has already rotated or expired it.

• Keeping a peer connection alive in JS while the page goes into a suspended or backgrounded state without handling recovery.

The fix is usually architectural: keep the peer connection in a long-lived object, make teardown explicit, and treat session renewal as a first-class path rather than an error path.

One practical pattern is to separate the avatar session from the UI component:

class AvatarCall {

}

class AvatarCall {

}

class AvatarCall {

}

That way, route changes or component remounts do not silently tear down the media session.

Distinguish network failure from session expiry

WebRTC sessions can appear to “drop” even when the transport is healthy if your backend session expires or your signaling credential becomes invalid. For developer-facing realtime avatar systems, this is especially common when the browser client is talking to your app server, which in turn talks to the avatar service.

A few concrete failure modes to check:

1. Token or session TTL expired: the media path is fine, but your app can no longer refresh or maintain the session.

2. ICE restart required: the network changed, but the client never renegotiated.

3. Reverse proxy or WebSocket timeout: signaling died while the browser peer connection remained open long enough to mask the problem.

4. Browser tab throttling: background tabs can delay timers and make keepalive/renegotiation logic unreliable.

If you control the backend, add timestamped logs around every session lifecycle event: create, join, refresh, renegotiate, end. When a drop happens, you want to answer two questions quickly:

• Did the browser lose media transport first?

• Did the backend decide the session was no longer valid first?

That ordering is usually enough to point you in the right direction.

Use ICE restart deliberately, not as a panic button

If the network changes mid-session, an ICE restart can recover a call without creating a brand-new session. But it is not free: you are renegotiating transport, and if your app retries too aggressively, you can make a transient problem worse.

The right strategy is usually:

• Wait for disconnected briefly, because short blips often self-heal.

• Move to recovery if you see sustained failure or the connection enters failed.

• Recreate the peer connection only after restart attempts fail.

In production, do not assume one browser state machine fits all. Mobile networks, corporate proxies, and tab suspension all produce different failure characteristics. If your app targets live sales conversations, a graceful fallback matters more than perfect recovery.

Where Protoface fits in this stack

This is where Protoface helps in a pragmatic way: you can keep the avatar/session plumbing out of the browser and use the surface that matches your architecture. If you are embedding a voice agent in a LiveKit-based stack, the quickstart examples and the LiveKit plugin path let you attach a synchronized talking face to an existing agent without inventing your own avatar pipeline. If you are managing sessions server-side, the REST API and docs at docs.protoface.com are the right place to check the exact request/response fields and lifecycle semantics.

For example, a backend might create a session and hand the client only the minimum data it needs, keeping API keys off the browser entirely:

import requests

print(resp.json())

import requests

print(resp.json())

import requests

print(resp.json())

The exact payload shape depends on the API version, so treat the above as illustrative. The main architectural point is that session creation, auth, and renewal stay on the server side, which reduces the number of places where a browser-side WebRTC drop can become an unrecoverable auth problem.

Build better observability than “call failed”

If you want to diagnose drops quickly, instrument the call path with a few high-signal events:

• Peer connection state transitions with timestamps.

• ICE candidate pair nomination and selected transport details.

• Session create/join/refresh/end events from your backend.

• Track-level events such as mute, unmute, ended, and replaceTrack.

• Sampled stats for RTT, bitrate, packet loss, and frame decode counts.

Correlate those with user-visible moments: button clicks, route changes, tab visibility changes, and any explicit reconnect UI. In practice, the fastest way to debug these issues is to build a narrow timeline, not to stare at packet traces first.

Also, keep an eye on the quality tier you choose for the avatar. Higher quality usually means more bandwidth and stricter performance sensitivity. If session drops cluster on low-bandwidth networks, the avatar may be pushing the connection harder than the user’s network can sustain.

Conclusion

Most WebRTC session drops in realtime avatar apps come down to one of four things: ICE connectivity, browser lifecycle bugs, backend session expiry, or overload on constrained networks. The fix is to instrument each layer separately, log peer connection state and stats, and make renewal/recovery explicit in your app design.

If you are building this on top of a realtime avatar stack, keep the browser thin, keep session management server-side, and verify the failure mode before adding retries. The docs at docs.protoface.com cover the supported integration surfaces and are the best reference for exact request shapes and lifecycle behavior. Start there, then reproduce the issue with state logs and stats enabled; you will usually find the bug faster than expected.