Introduction

If you are adding a realtime AI avatar to a Webflow e-commerce site, the hard part is not “getting video on the page.” The hard part is deciding where the control plane lives: in your app code, or inside an isolated embed. That choice affects security, latency, how much logic you can customize, and whether your team needs backend work at all.

This post compares two practical approaches for Webflow: custom code that talks to your own avatar/session backend, and an iframe embed that hosts the avatar experience for you. By the end, you should be able to choose the right model for your site, understand the implementation constraints, and avoid the usual mistakes around API key exposure, cross-origin behavior, and realtime media streaming.

How realtime avatars actually fit into a web app

A realtime avatar is not a pre-rendered video clip. It is usually a low-latency media pipeline that takes audio, generates or streams a synchronized face video, and keeps lip motion aligned with speech. In a browser, that typically means one of two things:

• Your frontend connects to a session backend and receives a media stream over WebRTC or a similar realtime transport.

• Your frontend embeds an already-contained experience that handles the transport, session lifecycle, and UI inside an iframe.

For Webflow, the distinction matters because Webflow is great at rendering and composing frontend experiences, but it is not a backend platform. If your avatar needs private credentials, session creation, rate limiting, per-user config, or dynamic instructions tied to commerce data, you need a real integration point somewhere.

Option 1: custom code in Webflow

Custom code means you own the page logic. In practice, that usually looks like:

1. Add a div or custom element in Webflow.

2. Load your own JavaScript bundle.

3. Call your backend to create or join a realtime avatar session.

4. Attach the resulting media stream to a video element or a custom player surface.

5. Wire store-specific events into the agent, such as product lookups, cart actions, or order status checks.

This is the right choice when the avatar is part of a broader application workflow. For example, a sales agent might need to read catalog metadata, personalize the script based on UTM parameters, or hand off to a human support queue. Those concerns are easier to manage when the browser talks to your backend rather than to an iframe.

Custom code: why teams choose it

The main advantage is control. You can decide exactly when a session starts, which model or voice to use, how long it can run, and how the avatar interacts with your existing systems. You can also integrate with your analytics, auth, and checkout flow without fighting iframe boundaries.

That said, custom code makes you responsible for a few things that are easy to underestimate:

• Credential safety: API keys must never be exposed in browser code.

• Session lifecycle: create, renew, and end sessions cleanly.

• Cross-origin media: WebRTC and autoplay policies can fail in subtle ways if you do not handle user gestures and permissions correctly.

• Operational work: retries, timeouts, and usage tracking move into your app.

In other words, custom code is powerful, but it is not “just an embed.” If you need direct access to the avatar session and the surrounding business logic, it is worth the extra work.

Custom code: a minimal backend-first pattern

If you do custom integration, the browser should not talk to the avatar API directly with a secret key. Put the secret on your server, create the session there, and return only the short-lived or client-safe data needed by the browser.

A typical backend call might look like this:

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

The exact request shape depends on the API surface you use, but the pattern is the same: keep the secret server-side, create the session there, then hand the browser only what it needs to join.

If you prefer Python, the same backend pattern is straightforward with the Python SDK. The following is illustrative; check the docs for the exact client methods and fields:

from protoface import ProtofaceClient

print(session.id)

from protoface import ProtofaceClient

print(session.id)

from protoface import ProtofaceClient

print(session.id)

Option 2: iframe embed in Webflow

An iframe embed is the opposite trade-off: the avatar experience is self-contained. You drop an iframe into Webflow, and the embedded app handles media, session setup, and interaction internally. For many marketing sites and smaller e-commerce flows, this is the fastest path to a working avatar.

The key property is isolation. The iframe runs on its own origin, so your browser code does not need to know any API secrets. That makes it much easier to ship something secure without building a backend. It also reduces the amount of Webflow custom code you need to maintain.

Iframe embed: what you gain and what you give up

What you gain:

• No backend: useful if your site is mostly static or managed by a non-platform team.

• No exposed API key: the browser never sees a secret.

• Fast integration: one embed snippet instead of session orchestration code.

• Operational guardrails: parent-origin allowlisting, per-embed voice and instruction overrides, plus rate limiting are easier to enforce in the embed layer.

What you give up:

• Less direct control: the embedded app owns the session flow.

• Harder deep integration: connecting the avatar to custom cart logic or internal tools is more limited.

• More boundary management: if you need parent-page events, you will rely on postMessage-style patterns rather than direct DOM access.

For many Webflow stores, that trade is acceptable. If the avatar is there to greet visitors, answer common questions, and qualify leads, the iframe model is usually the lowest-friction choice.

Embedding safely in Webflow

If you use an iframe, treat it like a separate application surface. A few practical rules help keep the integration stable:

• Set an explicit size and responsive container so the avatar does not reflow unpredictably on mobile.

• Test autoplay and audio behavior on Safari and mobile browsers, where media restrictions are stricter.

• Make sure the parent origin is allowlisted if the embed requires it.

• Do not try to “reach into” the iframe DOM from Webflow custom code; assume cross-origin isolation.

Also be realistic about UX. Realtime video faces are heavier than a chat widget. If the avatar is below the fold or in a product detail modal, you should check that the interaction still feels deliberate rather than distracting.

Where Protoface fits

Protoface is useful here because it supports both ends of the spectrum. If you are building a custom Webflow integration, you can manage avatars and sessions through the REST API or the Python SDK, and if your product is better served by a self-contained surface, the customer-managed iframe embed keeps secrets out of the browser while still letting you configure per-embed behavior.

For developers who want to wire avatars into an existing voice stack, there is also a LiveKit Agents plugin that drops a synchronized talking face into a voice agent. That matters if your Webflow experience is just the frontend wrapper around a larger realtime system.

If you want concrete implementation details, start with the docs and the quickstarts: docs.protoface.com and the examples linked from the quickstart repository. The code there is a better source of truth than any blog post for exact payloads and current session fields.

# Example shape only; see docs for exact client methods and fields

print(session)

# Example shape only; see docs for exact client methods and fields

print(session)

# Example shape only; see docs for exact client methods and fields

print(session)

Choosing between custom code and iframe

A good rule of thumb:

• Choose custom code if the avatar needs to participate in your business logic, identity model, or checkout workflow.

• Choose iframe if you want the fastest secure path to a realtime avatar on a Webflow page with minimal backend work.

Do not optimize for theoretical flexibility if the first version only needs to answer questions and qualify leads. On the other hand, do not force an iframe if your product depends on deeply integrated state. The wrong choice shows up later as awkward workarounds, not during the initial demo.

Conclusion

For Webflow e-commerce, custom code and iframe embeds solve different problems. Custom code gives you full control and is the better fit for rich product and account workflows. An iframe embed gets you to a secure, maintainable realtime avatar faster, especially when you want to avoid shipping a backend just to host an interaction surface.

If you are building this for real, start with the simplest integration that matches your needs, then tighten it only when the product demands it. For implementation details, session semantics, and current API shapes, use the official documentation at docs.protoface.com.