> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar Embed Widget

> Put your Digital Twin's talking avatar on any external website — visitors converse with it without signing in to Pria.

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.

<Note>The widget requires an **Anam avatar** configured on the Digital Twin (avatar, voice, intro message). Set that up first — see [Anam Avatar](/mdx/integrations/anam/introduction).</Note>

<Warning>
  **Cost warning.** Every anonymous visitor conversation consumes the Digital Twin's **pooled credits**. Always restrict the origin allowlist and set sensible usage limits before going live.
</Warning>

***

## 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.

***

## Create an embed (admin)

<Steps>
  <Step title="Open Avatar Embeds">
    In the Admin dashboard, open your Digital Twin instance and go to the **Avatar Embeds** section. It confirms your Anam avatar/voice binding — if it warns that no avatar is configured, finish the [Anam setup](/mdx/integrations/anam/introduction) first.
  </Step>

  <Step title="Create a new embed">
    Click **New embed** and fill in:

    * **Name** — for your own reference.
    * **Allowed origins** (required) — exact `scheme://host[:port]` values, one per line (e.g. `https://example.com`, `http://localhost:3000`). **No wildcards, no paths.** Only pages served from these origins can use the widget.
    * **Display** — title, greeting, theme, accent color, launcher label, placeholder image.
    * **Limits** — sessions per day, turns per session, session duration, concurrent sessions, and a daily credit ceiling.
  </Step>

  <Step title="Copy the embed key and snippets">
    Saving generates a browser-safe **embed key**. The **Snippets** panel on each embed row gives you copy-paste install code for both the script tag and the React component.
  </Step>
</Steps>

***

## Install the widget

### Script tag (any site)

```html theme={null}
<script src="https://pria.praxislxp.com/avatar-widget/v1/loader.js"
        data-embed-key="YOUR_EMBED_KEY"
        data-mount="#pria-avatar"
        data-api-base-url="https://pria.praxislxp.com/api/public/avatar/embed"
        async></script>
<div id="pria-avatar"></div>
```

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. You can also mount imperatively:

```javascript theme={null}
window.PriaAvatar.mount({ embedKey: 'YOUR_EMBED_KEY', mount: '#pria-avatar' });
```

### React component

```jsx theme={null}
import { PriaAvatarWidget } from '@praxis/avatar-widget';

<PriaAvatarWidget
  embedKey="YOUR_EMBED_KEY"
  apiBaseUrl="https://pria.praxislxp.com/api/public/avatar/embed"
  theme="light"          // 'light' | 'dark'
  mode="launcher"        // 'launcher' (floating button) | 'inline' (embedded panel)
  onSessionStart={() => {}}
  onSessionEnd={() => {}}
  onError={(e) => {}}
/>
```

***

## Lifecycle controls

From the Avatar Embeds admin panel you can manage each embed at any time:

| Action               | Effect                                              |
| -------------------- | --------------------------------------------------- |
| **Rotate key**       | Issues a new embed key (update your site's snippet) |
| **Disable / Enable** | Temporarily turns the embed off/on                  |
| **Revoke**           | Permanently invalidates the key                     |
| **Delete**           | Removes the embed configuration                     |

Disable and revoke take effect on the visitor's **next request** — fail-closed.

***

## Billing behaviour

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 per-embed **daily credit ceiling** caps worst-case spend.

***

## Troubleshooting

| Symptom                            | Fix                                                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Widget shows an error immediately  | Check the embed key is correct, the embed is **enabled**, and avatar embedding is enabled for the Digital Twin |
| `403 Forbidden` in the network tab | The page's origin isn't in the **Allowed origins** list — 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 per-embed limits (turns per session, session duration, daily credit ceiling)            |

***

## Related

* [Anam Avatar](/mdx/integrations/anam/introduction) — Configure the avatar the widget displays
* [Embed your Digital Twin (Web SDK)](/mdx/integrations/web/introduction) — Full chat UI embed for signed-in or identified users
* [Voice & Realtime Providers](/mdx/integrations/voice-providers/overview) — Compare avatar and voice options