Introduction

If you want to put an interactive SDR-style avatar on a marketing site, the hard part is not rendering a face. It is wiring the experience so the browser can safely talk to a realtime backend, stream audio and video without exposing credentials, and keep the UX responsive enough that it feels like a product feature instead of a demo.

This post shows how to embed a Protoface-hosted avatar in an Astro site using an iframe, with no backend in your app and no API key in the browser. By the end, you should understand the architecture, the security model, and the practical integration steps for adding a conversational avatar to a landing page or product site.

Why an iframe embed is the right default for marketing sites

For a marketing site, the usual alternatives are all awkward in different ways:

• Direct browser integration means you own session creation, token handling, and every CORS/security edge case.

• Custom WebRTC plumbing is overkill unless you are building the avatar experience as a core product surface.

• A static video clip gives you motion, but not interaction.

An iframe changes the trade-off. The host site only needs to render a sandboxed surface and pass a small amount of configuration. The embedded experience can then establish its own realtime session, negotiate media, handle voice input, and render lip-synced output without exposing backend credentials to the page.

That matters for Astro specifically because Astro sites are often deployed as mostly-static frontends. An iframe keeps the implementation simple: no server endpoints, no session signing in your app, and no client-side access to privileged API keys.

What is actually happening under the hood

An interactive avatar embed is not just “video in a box.” In practical terms, the browser is exchanging realtime media and control signals with an avatar service that coordinates speech, animation, and turn-taking. The avatar needs to know when the user starts speaking, when to listen, when to generate a response, and how to map audio into synchronized facial motion.

The iframe encapsulates that session lifecycle. Your site hands the embedded app a few parameters, and the embedded app handles the rest:

• session startup and teardown

• voice configuration

• custom instructions or behavior prompts

• rate limiting and abuse control

• parent-origin checks so the embed only loads where you expect it to

From a browser perspective, this is much cleaner than trying to wire a media session directly into your page. The parent window does not need access to the underlying API key, and it does not need to manage long-lived auth tokens. That is the right boundary for a marketing site.

Implementing the Astro page

In Astro, the integration is usually just a component that renders an iframe with the right source URL and sizing rules. You can keep it static, or parameterize it from frontmatter or environment-driven content if you want different campaigns to load different avatar behavior.

A minimal component might look like this:

<iframe
></iframe>

<iframe
></iframe>

<iframe
></iframe>

Two implementation details are worth calling out:

1. Use a predictable height. Realtime avatar UI tends to be taller than a static video element because it also needs transcript, controls, and state feedback. Reserve enough vertical space so layout does not jump.

2. Allow the permissions the embed actually needs. If the experience accepts voice input, the iframe needs microphone access. If it autoplays audio/video, the browser permission model may also require autoplay handling.

If your site is fully static, this is usually enough. If you need to swap prompt text or voice per page, keep those values in Astro props rather than hardcoding them into the component. That keeps the page content declarative and easy to review.

Security and operational constraints you should not skip

The main risk with embeds is that they become a generic attack surface if you do not constrain them. The right setup should enforce:

• Parent-origin allowlisting so the iframe is only embeddable from your domains.

• Per-embed voice and instruction overrides so each page can have a narrow, page-specific behavior profile.

• Per-IP and duration limits so a public page cannot be abused indefinitely.

• No API keys in the browser because client-side exposure is not acceptable for privileged access.

Operationally, this matters because marketing pages can spike traffic in ways that are hard to predict. A social post or product launch can create enough concurrency to stress the realtime layer. Rate limits and origin checks turn that from a security incident into a bounded capacity problem.

Also be realistic about browser behavior. Autoplay restrictions, muted-start requirements, microphone permissions, and mobile Safari quirks can all affect the first-second experience. Test the embed on at least one desktop browser and one mobile browser before shipping.

How the API fits when you need more control

For a pure iframe embed, you should not need to call the API from your Astro site. But it is useful to understand the control plane behind it, especially if you later want to generate embed-specific configuration from your own admin tool.

Protoface exposes a REST API for creating and managing avatars and realtime sessions. Requests are authenticated with an API key in the usual bearer-token style:

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

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

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

The exact request shape depends on the resource you are creating, so use the docs as the source of truth. The important design point is that your site should not make these calls directly if the key would end up in the browser. Generate or configure sessions server-side, or use the managed embed surface when you want to avoid backend code entirely.

If you prefer Python for operational tooling, the SDK gives you the same control without forcing you to hand-roll HTTP requests:

from protoface import ProtofaceClient

print(session)

from protoface import ProtofaceClient

print(session)

from protoface import ProtofaceClient

print(session)

That is useful for internal automation, not for the public marketing page. Keep the browser surface thin; keep privileged calls off the client.

A practical Astro setup pattern

A simple pattern is to create one reusable embed component and pass campaign-specific data in through props:

---

/>

---

/>

---

/>

Then style the container in your existing Astro layout so the embed participates in responsive design like any other hero element. Keep the page copy and the avatar prompt aligned. If the page is about pricing, the avatar should behave like a pricing assistant. If the page is a lead-gen landing page, keep the interaction short and focused on qualification.

One subtle but important point: do not treat the avatar as a general chatbot bolted onto the site. A good marketing-site embed has a narrow job. It should answer a bounded set of questions, guide users to the next action, and fail gracefully when the question is out of scope.

Where Protoface fits

This is exactly the kind of surface Protoface is meant to handle: the embed manages the realtime avatar session for you, while the browser only sees a standard iframe. That keeps the implementation compatible with static Astro deployments and avoids exposing credentials in client-side code.

If you later want to move beyond the embed, the same platform also supports a REST API, a Python SDK, and voice-agent integrations. But for an Astro marketing site, the iframe is the lowest-friction option and usually the safest one.

Testing, debugging, and rollout

Before shipping, validate a few concrete cases:

• Does the iframe load from every domain you intend to serve?

• Does microphone access prompt correctly on desktop and mobile?

• Do the voice and instruction parameters produce the right behavior?

• What happens when the rate limit is hit or the session expires?

Also test the embed inside the exact Astro layout you will ship. A hero section can mask overflow or height problems that are not obvious in a standalone page. If your design system includes responsive containers, make sure the iframe respects those constraints and does not create horizontal scroll.

If you are coordinating with design or marketing, it helps to treat the avatar as content with an operational budget. Decide up front what the avatar should do, how long a session should last, and what the fallback path is when the embed cannot initialize. That avoids a lot of “why did this page suddenly feel broken?” debugging later.

Conclusion

For an Astro marketing site, the cleanest way to add an interactive SDR avatar is usually an iframe embed: the browser gets a self-contained realtime UI, your page stays static, and privileged access never touches client-side code. The main engineering work is setting the right security boundaries, choosing sensible voice and instruction defaults, and making sure the embed behaves well in your layout and browsers.

If you want the implementation details, the configuration options, or the exact session payloads, start with docs.protoface.com. For operational control or more advanced integration patterns, the API and SDK are available too. For a marketing site, though, keep it simple: use the embed, test it carefully, and let the avatar do one job well.