Introduction

If you want to add an interactive employee onboarding avatar to a Vue 3 app, the main question is not “can I render a video?” It’s how to embed a realtime, conversational face that stays in sync with the agent behind it, while keeping credentials off the browser and the integration simple enough to ship.

This post shows one practical pattern: embed the avatar as a customer-managed <iframe> inside Vue 3, and treat the iframe as the boundary between your app and the avatar session. By the end, you should understand how to wire up the component, pass an allowed parent origin, think about session setup and rate limits, and decide when iframe embedding is the right choice versus a LiveKit agent plugin or backend-driven API flow.

Why an iframe is a good fit for onboarding

For employee onboarding, the avatar usually plays a very specific role: greet the user, explain steps, answer questions, and hand off to a human or knowledge base when needed. That means the UI requirements are different from a custom media pipeline. You often want:

• Fast integration in an existing Vue app.

• No API keys in frontend code.

• Strict control over who can embed the avatar and where.

• A session model that can be constrained by duration and per-IP usage.

An iframe gives you a clean boundary. The host app renders a normal Vue component, while the avatar experience runs in its own origin and manages realtime media, voice, and session state independently. That keeps browser code simpler and reduces the number of moving parts you have to own.

The Vue 3 embedding pattern

At the simplest level, your Vue component only needs to render an iframe and supply a source URL that represents the embed session. In practice, that URL is created or configured ahead of time, and the embed is restricted to a parent-origin allowlist so only your app can load it.

Here is a minimal Vue 3 component that treats the iframe as a self-contained onboarding widget:

<template>

<template>

<template>

A few details matter here:

• allow should include only the capabilities the embed actually needs. For a talking avatar, autoplay and media access are common.

• Use a fixed aspect ratio or explicit height so the layout doesn’t shift when the avatar loads.

• Keep the source URL in environment config, not in component code, so you can swap environments cleanly.

If the iframe needs to communicate basic state back to the parent app, use window.postMessage with strict origin checks on both sides. Don’t try to reach into the iframe DOM from Vue; that breaks the browser security model and will fail across origins anyway.

Session setup and what the browser should not know

The important architectural choice is that the browser should never see an API key. The iframe embed model is specifically useful when you want the avatar to be configured server-side or through the managed embed layer, while the page itself only receives a safe URL.

That separation matters because onboarding flows are often deployed on internal portals, staging environments, and admin dashboards. If you keep secrets in the browser, they get copied into network logs, extensions, source maps, and client bundles. Instead, create or manage the avatar/session outside the client and hand the app a URL that is already scoped to the allowed parent origin.

If you need to provision sessions programmatically, the REST API is the cleanest control plane. A server can create a session, apply custom instructions, and return an embed URL or session reference to the frontend. The exact fields depend on the API version, but the workflow is typically: authenticate server-to-server, create the resource, then hand the client a safe, constrained embed.

curl -X POST <a href="https://api.protoface.com/&lt;relevant-endpoint" data-framer-link="Link:{"url":"https://api.protoface.com/&lt;relevant-endpoint","type":"url"}">https://api.protoface.com/&lt;relevant-endpoint</a>> <br>}'

curl -X POST <a href="https://api.protoface.com/&lt;relevant-endpoint" data-framer-link="Link:{"url":"https://api.protoface.com/&lt;relevant-endpoint","type":"url"}">https://api.protoface.com/&lt;relevant-endpoint</a>> <br>}'

curl -X POST <a href="https://api.protoface.com/&lt;relevant-endpoint" data-framer-link="Link:{"url":"https://api.protoface.com/&lt;relevant-endpoint","type":"url"}">https://api.protoface.com/&lt;relevant-endpoint</a>> <br>}'

The exact endpoint and payload keys are documented in the API reference, so treat the snippet above as illustrative rather than copy-paste complete. The key point is the boundary: server code owns creation and authorization, browser code only consumes the embed.

Practical concerns: origin allowlists, rate limits, and failure modes

In onboarding, the avatar is usually embedded in a page that has predictable origins: your intranet, an HR portal, or a customer-specific subdomain. That makes origin allowlisting a strong default. It prevents random third-party sites from framing the avatar session and helps keep the UX predictable.

Two other guardrails are worth calling out:

• Per-embed voice and instructions. Use these to tailor the behavior of the avatar to a specific onboarding flow, such as IT setup, benefits, or first-day logistics.

• Per-IP and duration limits. These are useful for preventing abuse and containing cost, especially if the avatar is exposed in a portal with many users or anonymous traffic.

On the frontend, plan for what happens when the iframe fails to load. Common causes are a bad parent origin, a blocked media permission, or a session that has expired. A good host app shows a fallback card with a retry action and a support link, rather than leaving a blank rectangle on the page.

Also remember that realtime avatars depend on low-latency streaming. In the browser, that means media setup and connection negotiation can take a few seconds. If your onboarding page does other work, keep the avatar below the fold or lazy-load it after the first panel renders, so the initial UI feels responsive.

When to use an iframe versus a voice-agent plugin

The iframe model is ideal when the avatar is part of the web experience itself. But not every avatar belongs in a browser frame. If you are building a voice agent with LiveKit, the better fit is often a server-side agent plugin that adds a synchronized talking face to the agent pipeline.

That path is useful when the avatar is coupled to agent audio and you want the video face to track the live conversation in the same media session. In that setup, your application logic stays in the voice agent, and the avatar becomes a rendering surface for the agent’s output rather than a standalone embed.

For example, the LiveKit plugin can be added to an agent process in Python so the agent gains a lip-synced visual presence. The plugin keeps the avatar aligned with the agent’s realtime turn-taking and speaking state, which is a different problem than embedding a browser widget.

from livekit.agents import Agent<p></p>

from livekit.agents import Agent<p></p>

from livekit.agents import Agent<p></p>

If your use case is “put a talking onboarding guide on a page,” start with the iframe. If your use case is “give my voice agent a face inside a realtime call,” start with the agent plugin. The right choice is mostly about where the media session lives and which side owns orchestration.

Testing the embed in Vue 3

A useful way to verify the integration is to test in three layers:

1. Embedding. Does the iframe load in your Vue page without layout issues?

2. Policy. Is the parent origin allowed, and are media permissions accepted?

3. Session behavior. Do voice, instructions, and rate limits behave as expected under refresh and retry?

In Vue, keep the component dumb and move any session orchestration to a composable or backend endpoint. For instance, if you need to fetch an embed URL from your API, do it in a lifecycle hook and render a loading state until the URL arrives. That keeps the component reusable and avoids hard-coding environment-specific values.

<script setup>

<script setup>

<script setup>

This pattern also gives you one place to rotate configuration, enforce tenant-specific settings, and handle error responses from your backend without exposing anything sensitive to the browser.

Protoface as the managed embed layer

This is where a managed iframe embed is a good fit. Protoface provides customer-managed iframe embeds designed for exactly this kind of integration: add an interactive avatar to a site without shipping an API key to the browser, restrict it by parent origin, and constrain usage with per-embed limits. That makes it easier to drop an onboarding avatar into Vue 3 while keeping the integration boundary clean.

If you need to provision or automate sessions, use the REST API from your server. If you want to inspect sessions, manage API keys, or experiment interactively, the developer dashboard is the right place to do that. For implementation details and current request shapes, refer to the docs at docs.protoface.com.

Conclusion

Embedding an employee onboarding avatar in Vue 3 is mostly an exercise in choosing the right boundary. An iframe keeps the frontend simple, keeps credentials out of the browser, and lets you enforce origin and usage constraints centrally. In practice, that is usually the most maintainable approach for onboarding flows.

If you need a browser-native widget, start with the iframe pattern shown above. If you need deeper agent integration, use the server-side voice-agent path instead. Either way, keep the media session, configuration, and authorization logic out of the Vue component itself.

For implementation details, current API shapes, and quickstarts, start with the public docs at docs.protoface.com and the relevant examples in the GitHub repositories linked there.