Introduction

WebRTC failures in production are annoying precisely because they rarely fail in one obvious place. In a banking voice agent, the user reports “the avatar froze” or “the call dropped,” but the actual fault may be anywhere in the chain: signaling, TURN allocation, NAT traversal, media negotiation, RTP transport, browser tab lifecycle, or your application code reacting badly to a transient network event.

This post walks through a real debugging approach for a WordPress-based banking voice agent that uses a browser-embedded realtime avatar. By the end, you should be able to isolate whether the problem is in WordPress, the browser, the WebRTC transport, or the voice-agent backend; gather the right evidence; and harden the system so intermittent drops become diagnosable instead of mysterious.

Start by separating “the page broke” from “the media path broke”

The most common mistake is treating the website and the call as one system. In a WordPress deployment, those are different failure domains:

• Page delivery: PHP, caching plugins, CDN behavior, security headers, CSP, iframe sandboxing, cookie policies.

• Call setup: initial auth, session creation, ICE gathering, SDP exchange, TURN reachability.

• Media transport: RTP/RTCP over the chosen candidate pair, jitter, packet loss, renegotiation, track replacement.

• Application lifecycle: browser tab visibility, React/DOM unmounts, WordPress block re-renders, iframe reloads, token expiration.

When the report is “dropped WebRTC,” the first question is simple: did the iframe or page reload, or did only the media path fail? In practice, I ask for three timestamps:

1. When the user clicked “start.”

2. When the avatar first rendered audio/video.

3. When the failure became visible.

If the entire iframe disappears or the page navigates, you are probably not debugging WebRTC yet. You are debugging WordPress lifecycle behavior, a plugin conflict, or a security policy forcing a reload.

Instrument the browser before you change infrastructure

For WebRTC, the browser has the best view of the problem. Use chrome://webrtc-internals during a repro, and look for:

• ICE state transitions: new → checking → connected → disconnected or failed

• Selected candidate pair changes, especially relay vs. host vs. srflx

• Outbound/inbound RTP packet loss, jitter, and RTT

• Track end events or transceiver changes

That lets you distinguish a transient network hiccup from a hard failure. A short disconnected state with recovery is not the same as failed. If the browser never gets out of checking, the issue is usually signaling or TURN/ICE reachability. If it connects and later degrades, focus on network quality, NAT rebinding, tab suspension, or session timeout.

It also helps to log browser-side WebRTC events into your app. In a custom integration, wire up the important transitions so you can correlate them with server logs:

const pc = new RTCPeerConnection(config);

};

const pc = new RTCPeerConnection(config);

};

const pc = new RTCPeerConnection(config);

};

If you are using an iframe-based embed, you won’t own the peer connection directly, but you can still observe page events, iframe reloads, and whether the embed URL is being regenerated by WordPress. In WordPress, a “helpful” caching or security plugin is often the hidden culprit: it may strip query params, rewrite headers, or force reloads on route changes.

Check the failure modes that WordPress adds

WordPress changes the debugging surface in a few predictable ways:

• Caching plugins can serve stale embed HTML or strip per-session parameters.

• Content Security Policy can block the iframe, websocket signaling, or media endpoints if not explicitly allowed.

• Security plugins may inject headers that interfere with cross-origin frames or auth flows.

• Theme scripts can re-render the embed container, which destroys the iframe and with it the session.

• Page builders can wrap your embed in elements that resize unexpectedly, causing layout-driven reload logic to trigger.

For a banking agent, it is also common to see stricter browser behavior around third-party cookies and storage. If your implementation depends on cross-site state, test in a privacy-hardened browser profile. A session that works on localhost can fail when deployed under a different origin policy.

One particularly nasty pattern is the “soft refresh”: the page doesn’t fully navigate, but WordPress replaces the block markup. From WebRTC’s point of view, that’s still a teardown. If the user’s browser is in the middle of ICE consent checks, the peer connection dies and the avatar drops.

Use the right debug signals from the backend

On the backend, you want enough logs to answer three questions:

1. Was a realtime session created successfully?

2. Was media negotiation completed, and if so, with which transport path?

3. Did the session end because the client disconnected, the server timed out, or the network path failed?

For a voice agent, a drop can be caused by upstream ASR/TTS issues too, but those usually show up as silence or stalled responses rather than a true WebRTC teardown. In logs, separate “agent stopped speaking” from “transport stopped delivering frames.” Those are different classes of bugs.

If your backend creates sessions via a REST API, verify the session lifecycle independently from the browser. A quick curl check is useful when you suspect auth, rate limiting, or provisioning problems:

curl -s https://api.protoface.com/sessions \
}'

curl -s https://api.protoface.com/sessions \
}'

curl -s https://api.protoface.com/sessions \
}'

The exact request shape depends on the endpoint and fields in the docs, but the point is to prove whether session creation is healthy before you debug the browser. If a session is created, then dies when embedded in WordPress, the browser/page is the likely fault domain. If session creation fails intermittently, look at credentials, rate limits, or upstream availability.

Triage the network path like a production incident

When WebRTC drops only for some users, the network path is usually involved. In a banking context, users may be behind corporate proxies, carrier-grade NAT, or aggressive firewall policies. That means you should test at least three environments:

• Local developer network

• Residential broadband

• Corporate or VPN network

In real deployments, TURN matters. If direct peer-to-peer candidates fail, the connection falls back to relay candidates. If relay is unavailable or misconfigured, users behind strict NATs will connect inconsistently. In practice, “works at my desk, fails for customers” is frequently a TURN reachability issue disguised as an avatar bug.

Watch for these signs:

• connected on one network and failed on another

• Very high RTT or packet loss before the disconnect

• ICE selecting a host candidate that later becomes unreachable after network switching

• Disconnects when the user switches from Wi-Fi to cellular or changes VPN state

If the issue is mobile-specific, the browser may be suspending the tab or renegotiating network routes. That’s not exotic; it is simply how mobile browsers behave under memory and power pressure.

How Protoface fits when you want a deterministic embed path

If the banking agent is embedded as a customer-managed iframe, you can remove a lot of WordPress-specific risk: no API key in the browser, no fragile client-side session bootstrapping, and a cleaner boundary between your site and the realtime avatar session. The embed model also gives you parent-origin allowlisting and per-embed controls, which are exactly the kinds of constraints you want in a regulated flow.

For developers who are building the voice agent itself, the LiveKit integration is often the simplest way to attach a synchronized avatar to an existing agent. The plugin on PyPI and the example repo make it straightforward to keep the debugging surface small while you validate the media path and session lifecycle. If you are working in that stack, the examples in the GitHub organization and the docs at docs.protoface.com are the right place to confirm the exact integration shape.

A minimal LiveKit-side sketch looks like this:

from livekit.agents import Agent

)

from livekit.agents import Agent

)

from livekit.agents import Agent

)

The value here is not the snippet itself; it is the fact that you can keep the avatar lifecycle aligned with the voice-agent lifecycle. When the agent starts, the avatar starts. When the session ends, both end. That makes postmortems much easier because you can correlate agent logs, WebRTC state, and user-visible behavior with a single session identifier.

Practical checklist for the next incident

When the next drop happens, capture the following before making changes:

• Browser console logs and webrtc-internals dump

• Whether the iframe reloaded or only media stopped

• WordPress plugin/theme changes in the last deployment

• Network type, browser version, and whether a VPN was active

• Server-side session creation and teardown logs with timestamps

Then debug in this order: page lifecycle, signaling/session creation, ICE/TURN reachability, then media quality. That order avoids a common time sink: replacing infrastructure when the real issue is a DOM re-render or a cache rule.

Conclusion

WebRTC drops are rarely a single bug. In a WordPress-based banking voice agent, the page layer and the realtime media layer interact in ways that make intermittent failures look random unless you instrument them separately. If you capture browser state, session logs, and WordPress lifecycle events, you can usually reduce “the avatar dropped” to one of a handful of root causes within a single repro.

If you are building or debugging this stack, keep the boundary between the website and the realtime session as clean as possible, and verify the call path with the browser tools first. For integration specifics, see docs.protoface.com. If you want to compare implementation patterns, the quickstarts linked from the GitHub organization are a good starting point.