Embedding a Realtime AI Sales Avatar on a Website with an iframe
Embed a realtime AI sales avatar on a website with a secure iframe: no browser API keys, origin controls, rate limits, and voice config.
Introduction
Adding a realtime AI sales avatar to a website sounds simple until you try to do it without creating a security mess or a latency disaster. If the avatar is meant to talk, listen, and stay synchronized with an underlying voice agent, you need a delivery path that handles media streaming, state, and auth cleanly. You also need something that works on a normal marketing or product page, not just inside a custom app shell.
This post shows a practical way to embed a realtime avatar using an iframe, with the right boundaries: the browser never sees an API key, the website owner can control where the embed is allowed to run, and the avatar can be configured with per-embed voice and instructions. By the end, you should understand the architecture trade-offs, how to wire the embed into a site, and when to use the iframe approach versus direct API integration.
The core problem: realtime video faces are stateful media systems
A “sales avatar” is not just a video player. In a realtime setup, the avatar is typically driven by a voice agent or conversational backend that emits text, audio, and control signals. The avatar layer then turns those signals into synchronized facial animation and lip movement. That means you are dealing with:
Low-latency media delivery: audio and video need to stay close enough in time that the face matches the voice.
Session state: the avatar should know which conversation it belongs to, what voice/instructions it is using, and when to tear down resources.
Browser security: if you expose backend credentials in frontend code, you have a problem immediately.
Operational controls: you need rate limits, origin restrictions, and a way to monitor usage.
For developer teams, the key design question is whether the browser should talk directly to the avatar service or whether the avatar should be wrapped in a controlled, customer-managed surface. For public websites, the iframe approach is often the cleanest option because it isolates the media session and keeps credentials off the page.
Why iframe embeds are the right default for public websites
An iframe embed is a good fit when you want to drop an interactive avatar into a landing page, support page, or product experience without building a custom frontend integration. The pattern is straightforward: the host page loads a URL that renders the avatar experience, and the iframe handles the realtime session internally.
The practical advantages are:
No backend required on the customer site: you can integrate with a single snippet.
No API key in the browser: credentials stay server-side inside the avatar platform.
Origin control: parent-origin allowlisting limits where the embed can run.
Operational guardrails: per-IP and duration rate limits help keep usage predictable.
Per-embed behavior: different pages can use different voices or custom instructions.
That last point matters for sales use cases. A pricing page avatar should probably behave differently from a support page avatar. One embed might qualify leads, another might answer product questions, and both can be backed by the same underlying platform but with different prompt and voice configuration.
What the browser actually does
At a protocol level, the iframe is just the public entry point. The realtime work happens inside the embedded experience, which can establish the necessary streaming session and keep the avatar synchronized with conversation state. The host page should only need to do two things:
Allow the iframe to render in the layout you want.
Optionally pass configuration that is safe to expose, such as an embed identifier or customer-specific parameters.
What you should not do is place an API key in JavaScript and call the avatar service directly from the page. Even if you think the endpoint is “internal,” browser code is public code. If the avatar needs privileged creation or management operations, do that from your server or via a managed embed flow.
A minimal embedding pattern
The exact embed URL and parameters are defined in the docs, but the shape of the integration will look familiar. You add an iframe, size it appropriately, and let the embedded app manage the session.
In practice, the important browser permissions are microphone and autoplay. If your experience includes user voice input, the iframe must be allowed to capture audio. If the avatar plays voice back, autoplay handling needs to be correct or the first interaction may be blocked by browser policy. If you are embedding on a marketing page, test this in Chrome, Safari, and mobile Safari early; media permissions and autoplay policies differ enough to surprise you.
Security and operational controls you should actually care about
For customer-facing embeds, the security model matters more than the animation quality. A few concrete controls are worth insisting on:
Parent-origin allowlist: only approved website origins should be able to host the embed.
Rate limits: both per-IP and duration limits prevent accidental overuse and obvious abuse.
Server-side configuration: anything sensitive, such as API keys or privileged session creation, should stay off the browser.
Clear session boundaries: a realtime avatar should have explicit lifecycle management so you can terminate or recycle sessions deterministically.
These are not nice-to-haves. Realtime media sessions are expensive relative to ordinary HTTP requests, and they can be abused easily if you expose them without guardrails. If the page can be embedded by arbitrary origins, it is easy for someone to copy your iframe and run up usage. If the embed is not rate-limited, a single bot can create an outsized cost problem.
When you need backend control, use the API from your server
Even if the browser integration is iframe-based, you will often still want server-side control for provisioning avatars or sessions. That is where the REST API belongs. It is authenticated with API keys and should be called only from trusted backend code.
A simple creation request might look like this:
The exact fields depend on the API surface in the docs, but this is the general pattern: create or update an avatar definition on the backend, then attach that avatar to a session or embed. If you are used to building voice agents, think of the avatar as a presentation layer that is attached to a realtime conversational session rather than a standalone asset.
How this fits into a developer workflow
In a typical team workflow, the browser embed is just one piece of the system. You might prototype the avatar behavior in the dashboard playground, validate the voice and instructions, then connect a production embed to the approved website origin. For higher-level automation, the Python SDK is useful for provisioning and lifecycle management in internal tooling.
If you are building the surrounding app in Python, this is the cleanest way to keep secrets on the server while still giving your frontend a realtime avatar experience through a managed embed.
Where the iframe approach is the right abstraction
This pattern is especially useful when the avatar is part of a customer-facing funnel rather than a deeply integrated product feature. A sales page, onboarding flow, FAQ assistant, or “talk to our team” page usually does not justify building a fully custom WebRTC frontend. The iframe gives you a controlled, production-friendly surface with less code and fewer moving parts.
It is also a better default when multiple non-engineering teams need to manage content. A product marketer can update prompt wording or voice selection without asking engineering to redeploy frontend code. Meanwhile, engineers retain control over which origins can embed the experience and how usage is constrained.
Common gotchas
Autoplay and mic permissions: test the embed in real browsers, not just desktop Chrome.
Responsive layout: reserve enough height for the avatar UI so it does not collapse on mobile.
Prompt drift: keep the avatar instructions short and specific; long prompts often produce inconsistent behavior.
Cost visibility: because usage is billed by quality tier, make sure you understand which tier your embed is using before sending traffic.
Origin management: if the same embed appears on multiple domains, update the allowlist deliberately rather than treating it as an afterthought.
One subtle issue is conversation ownership. If the avatar is embedded on a public page, you need to decide whether each page load creates a new session or whether you want a more persistent conversation identity. That choice affects analytics, handoff logic, and how you reconnect after reloads or network interruptions.
Where Protoface fits
Protoface gives you the backend and embed surfaces needed for this pattern: a REST API and Python SDK for server-side management, plus customer-managed iframe embeds for browser delivery. For a website sales avatar, the iframe is the most relevant surface because it keeps the browser free of API keys while still letting you control origin access, voice, instructions, and usage limits. The implementation details are documented at docs.protoface.com, and the quickstarts linked from the GitHub repository are useful if you want to compare integration styles before you commit to one.
Conclusion
If you want to embed a realtime AI sales avatar on a website, the safest and simplest approach is usually a managed iframe embed backed by server-side session and avatar configuration. That gives you a clean separation of concerns: the browser renders the experience, the backend owns credentials and policy, and the avatar service handles the realtime media plumbing.
Build it by starting with a constrained embed, test browser permissions and layout early, and keep the conversational instructions tight. If you need deeper control over avatar/session lifecycle, use the API or Python SDK on the server. For implementation details and current field names, start with the docs.