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 login. Your Digital Twin stays the brain (instructions, knowledge vault, configured tools); the avatar handles voice and video.

The widget requires an Anam avatar configured on the Digital Twin (avatar, voice, intro message). Set that up first — see Anam Avatar.

Cost warning. Every anonymous 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.
Sessions are anonymous — no per-user memory or conversation history is created.
The avatar’s answers come from your Digital Twin’s configured conversation model and knowledge, restricted to read-only tools (e.g. searching the Twin’s documents). The widget cannot trigger actions like sending email.

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.

Enable Avatar Embed on the Digital Twin

In the Admin dashboard, edit your Digital Twin instance and turn on the Avatar Embed setting. Embedding is off by default — while it’s off, every widget request is refused.

Allow your site's origin

Add your site to the twin’s Authorized Public URLs (in the instance’s Integrations settings) as an exact scheme://host[:port] origin (e.g. https://example.com, http://localhost:3000). No wildcards, no paths. 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 on 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.

The embed key is the Digital Twin’s public instance 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:

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 Avatar Embed off	Stops all new widget sessions for the twin
Remove an origin from Authorized Public URLs	Blocks pages on that origin from starting sessions
Deactivate the instance or 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 — per visitor, per minute
Turns per session — capped (50 by default)
Session duration — capped (30 minutes by default), plus a 5-minute idle timeout
Concurrent sessions — capped per embed (25 by default)
Credit precheck — every turn is checked against the twin’s pooled credit balance before it runs

Billing behavior

Each completed voice turn is billed server-side against the institution’s pooled credits the moment the turn finishes. If a visitor closes the tab mid-conversation, completed turns are already accounted for and abandoned sessions are closed automatically — nothing is double-charged. The built-in session and turn limits cap worst-case spend.

Troubleshooting

Symptom	Fix
Widget shows an error immediately	Check the embed key matches the twin’s public instance ID and Avatar Embed is enabled on the Digital Twin
`403 Forbidden` in the network tab	The page’s origin isn’t in the twin’s Authorized Public URLs — entries must match exactly (scheme, host, port)
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

Authentication

REST API

Runtime API

Administrator API

JavaScript SDK

Web & Chat Integrations

LMS Integrations

Voice & Avatars

MCP Server

Other Services

Avatar Embed Widget

How it works

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

​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

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