Avatar Embed Widget

The Avatar Embed Widget lets you drop your Digital Twin’s animated, talking avatar onto any website. Visitors click the launcher, grant microphone access, and speak with the avatar — no Pria account, no sign-in. Your Digital Twin stays the brain (instructions, knowledge vault, tools); the avatar handles voice and video.

The widget requires an Anam avatar configured on the Digital Twin (avatar, voice, intro message). The widget always uses it, whatever voice provider the twin uses in Convo Mode. Set it up first — see Anam Avatar.

Cost warning. Every visitor conversation consumes the Digital Twin’s pooled credits. Built-in rate and session limits bound worst-case spend, but always keep the origin allowlist tight before going live.

How it works

Visitor's browser → widget loader → Pria public embed endpoint → avatar session
       (embed key only)                  (origin-checked)        (your Twin answers)

The browser only ever holds a public embed key and a short-lived session token kept in memory — nothing is written to cookies or local storage, and no server API keys or Pria app credentials are involved.
Each visit gets its own visitor account, created automatically. Memory is off for visitors, and they cannot pick an assistant.
Every conversation is recorded and billed like any other: it appears in the twin’s history with the credits each exchange used. Visitors who open the widget but never speak are removed automatically.
The avatar answers with your Digital Twin’s own model, knowledge and tools. Visitors are anonymous, so turn off any tool they should not be able to trigger (Instance Settings → Tools).

Privacy policy

If the Digital Twin’s account has a privacy policy, the widget shows it before the conversation starts. The visitor selects I accept to talk, or Not now to close. Because every visit is a new visitor, each visit asks again, and an updated policy is shown with a note.

Enable the embed (admin)

Configure the Anam avatar

Make sure the Digital Twin has an Anam avatar and voice configured — see Anam Avatar. Without it, embed sessions cannot connect.

Turn on the embed

In the admin area, edit your Digital Twin and turn on Allow React Component Embed (Configuration → Access & Membership). Embedding is off by default — while it’s off, every widget request is refused.

Make sure the twin pools credits

Visitors have no credits of their own, so Pool Credits must be on. A twin that does not pool credits refuses widget sessions.

Allow your site's origin

Add your site to the twin’s Public Authorized URLs (under Integrations) as an exact scheme://host[:port] origin (e.g. https://example.com, http://localhost:3000). No wildcards, no paths. Unlike the Web SDK, the widget does not accept subdomains of a listed site. Only pages served from listed origins can start widget sessions — requests from anywhere else get a 403.

Generate the install snippet

Open the Integration Wizard (Instance Settings → Integration, or the Integration button above the admin Instances List), pick the Avatar widget target, and copy or download the generated code. It comes preconfigured with your twin’s embed key and display options, and warns you while the embed is off.

The embed key is the Digital Twin’s Public ID — a public identifier, not a secret. The security boundary is the origin allowlist plus the built-in usage limits, so keep the allowlist tight.

Script tag (any site)

<div id="pria-avatar"></div>
<script src="https://pria.praxislxp.com/avatar-widget/v1/loader.js"
        data-embed-key="YOUR_TWIN_PUBLIC_ID"
        data-mount="#pria-avatar"
        data-api-base-url="https://pria.praxislxp.com/api/public/avatar/embed"
        data-theme="light"
        data-mode="launcher"
        data-title="Your Twin's Name"
        async></script>

Options via data-* attributes: data-theme (light | dark), data-mode (launcher for a floating button, inline for an embedded panel), data-title (header text), and data-skip-mic-prompt="true" to skip the microphone pre-prompt. The loader adds a single window.PriaAvatar global and one scoped stylesheet. Multiple widgets per page are supported when each has its own mount element.

JavaScript / React apps (imperative mount)

In a single-page app, load the same script (without the data-* attributes) and mount when your component is ready. mount() returns a function that unmounts the widget — call it when your component goes away:

const unmount = window.PriaAvatar.mount({
  embedKey: 'YOUR_TWIN_PUBLIC_ID',
  mount: '#pria-avatar',
  apiBaseUrl: 'https://pria.praxislxp.com/api/public/avatar/embed',
  theme: 'light',          // 'light' | 'dark'
  mode: 'launcher',        // 'launcher' (floating button) | 'inline' (embedded panel)
  title: "Your Twin's Name",
  onSessionStart: () => {},
  onSessionEnd: () => {},
  onError: (err) => console.error('Pria avatar error', err),
});

The Integration Wizard generates both variants for you, prefilled with your twin’s embed key.

Lifecycle controls

You control the embed through the Digital Twin’s own settings:

Action	Effect
Turn Allow React Component Embed off	Stops all new widget sessions for the twin
Remove an origin from Public Authorized URLs	Blocks pages on that origin from starting sessions
Deactivate the Digital Twin or its account	Disables the embed along with everything else

Every change is checked on the visitor’s next request — fail-closed.

Built-in limits

Every embed is protected by automatic platform limits — no configuration required:

Session creation rate — 30 per minute per visitor address
Sessions per day — 500 per Digital Twin
Concurrent sessions — 25 per Digital Twin
Turns — 50 per session, at most 30 per minute, one at a time
Session duration — 30 minutes, plus a 5-minute idle timeout
Credit check — every turn is checked against the twin’s pooled credit balance before it runs

Billing behavior

Each completed voice turn is billed against the Digital Twin’s pooled credits the moment the turn finishes, under the same rules as any conversation: the twin’s balance, automatic top-ups from its account, and any credit limits you set (per user, per twin or per 24 hours). If a visitor closes the tab mid-conversation, completed turns are already accounted for and abandoned sessions are closed automatically — nothing is double-charged.

Troubleshooting

Symptom	Fix
Widget shows an error immediately	Check the embed key matches the twin’s Public ID, Allow React Component Embed is on, and the twin pools credits
`403 Forbidden` in the network tab	The page’s origin isn’t in the twin’s Public Authorized URLs — entries must match exactly (scheme, host, port)
“Please accept the privacy policy…”	The visitor closed the policy; it must be accepted before talking
Avatar never connects	Verify the Anam avatar/voice binding on the Digital Twin and the Anam account status
Sessions end abruptly	You may be hitting the built-in limits (turns per session, session duration, idle timeout) or the twin is out of credits

Anam Avatar — Configure the avatar the widget displays
Embed your Digital Twin (Web SDK) — Full chat UI embed for signed-in or identified users
Voice & Realtime Providers — Compare avatar and voice options

Overview

Getting Started

LMS Integrations

Voice & Avatars

Web & Chat Integrations

MCP Server

JavaScript SDK

Authentication

REST API

Runtime API

Administrator API

Avatar Embed Widget

How it works

Privacy policy

Enable the embed (admin)

Install the widget

Script tag (any site)

JavaScript / React apps (imperative mount)

Lifecycle controls

Built-in limits

Billing behavior

Troubleshooting

​How it works

​Privacy policy

​Enable the embed (admin)

​Install the widget

​Script tag (any site)

​JavaScript / React apps (imperative mount)

​Lifecycle controls

​Built-in limits

​Billing behavior

​Troubleshooting

​Related

How it works

Privacy policy

Enable the embed (admin)

Install the widget

Script tag (any site)

JavaScript / React apps (imperative mount)

Lifecycle controls

Built-in limits

Billing behavior

Troubleshooting

Related