Skip to main content

Fastest path: the Integration Wizard

The quickest way to embed your Digital Twin is the built-in Integration Wizard — a visual configurator that generates ready-to-use embed code for you. You pick where the twin will run, configure how the widget looks and behaves with a live preview, then copy or download the finished file. No hand-editing of SDK templates required.
The wizard replaces the old copy-and-edit-a-template workflow for most integrations. The manual Installation, Integration, and Configuration steps below are still fully supported for when you want complete control or to understand what the generated code does.

Where to find it

Instance Settings → Integration

Open your Digital Twin’s Instance Settings and select the Integration tab. The wizard is preset to the current twin, so you go straight to choosing a target.

Admin Instances list → Integration

Admins can open the wizard from the Integration button on the Instances list and pick which Digital Twin to generate code for.
From your Digital Twin, open the + options menu in the message bar, choose Settings, then Instance:
Digital Twin home screen with the plus options button in the message bar highlighted.

Open the + options menu in the message bar.

Options menu open with the Settings item highlighted.

Select Settings from the options menu.

Settings submenu with the Instance item highlighted.

Choose Instance to open Instance Settings.

How it works

1

Choose your Digital Twin

From the admin Instances list, select the twin to embed. (Skipped when you launch from Instance Settings — it uses the current twin.) The wizard warns you if the twin has no picture, since the widget button would otherwise show Pria’s default logo.
2

Pick a target

On the Integration tab, choose where the twin will run:
Instance Settings Integration tab showing the target picker with Web page, React, Flask, Canvas, Claude and Avatar options.

The Integration tab with the target picker.

3

Configure appearance & behavior

Use the visual configurator (with a live preview) to set the button position, button size, and toggles such as full screen, open on load, and Start in Convo mode (voice). An Advanced section exposes options like allowPop, noUI, and custom container IDs.
Integration wizard appearance step showing position presets, button size, and behavior toggles.

Configure the widget's position, size and behavior with a live preview.

4

Get the code

Preview the generated file, then copy it to your clipboard or download it. Paste it into your site — it works as-is.
Integration wizard code step showing the generated snippet with copy and save controls.

Preview the generated code, then copy or download it.

Visitor identity

The wizard offers a Visitor mode toggle that decides how users are identified:
  • On (default): the generated code gives each visitor a reusable guest identity — no sign-in required, and dormant guests are cleaned up automatically. Ideal for public, anonymous embeds.
  • Off: the code exposes a seam for your own sign-in, so you can pass real user identity (email, name, course, etc.) from your application.
Prefer to hand-code your integration, or want to understand exactly what the wizard produces? Keep reading — the sections below walk through installing the SDK and configuring it manually.

Integration Process

The integration process is straightforward:
  • Download and install the Web SDK,
  • Choose between Limited or Standard Integration
  • Further configure your integration (digital twin, user identity, display options)
Looking for a voice avatar instead of the full chat UI? The Avatar Embed Widget puts your Digital Twin’s talking avatar on any website with a single script tag — visitors converse with it anonymously, no user identity required.

Installation

Download the Web SDK and install the Javascript file in your website.

Integration

Choose between limited or standard integration option to integrate into your website.

Configuration

Customize the setup to specify which Digital Twin to connect to, User Identity and various display options.

Prerequisites

Before you begin, ensure you have:
  • Web development access to your target website or application
  • A Praxis AI Digital Twin instance created at pria.praxislxp.com
  • Your Digital Twin’s public instance ID (found in Configuration & Integrations)
  • HTTPS enabled on your website (required for secure SDK communication)
  • For public Digital Twins: Your domain added to Authorized Public URLs in the Digital Twin settings
Estimated setup time: 10-15 minutes for Limited Integration, 30+ minutes for Standard Integration with custom logic.

Installation

Download the Pria Web SDK file and save it locally on your website under the name pria-sdk-web.js
This SDK provides all routines for secure initialization and integration with your Digital Twin in a web application.
For Canvas LMS integration, refer to Custom Theme Canvas Install Guide
Public Digital Twin Security ConsiderationsWhen making a Digital Twin publicly accessible (without user authentication), you must take the following precautions:
  1. Credit Management
    • Set the Digital Twin to “Do Not Pool Credits” to prevent shared credit exploitation
    • Configure a reasonable credit allocation (e.g., 50 credits) for new guest registrations
    • Enable the Guest UI mode for anonymous access
    • Disable Use Location to prevent unwanted pop-ups
  2. Access Control
    • Add your domain (e.g., https://your-domain.com) to the list of Authorized Public URLs
    • Only domains in this whitelist will be able to embed and access the Digital Twin
  3. Tool Restrictions
    • Disable tools that could be exploited: call_rest, send_email, call_canvas, save_to_file, etc.
    • This reduces token usage and prevents malicious use of system capabilities
  4. Prompt Engineering
    • Carefully craft your system prompt to keep conversations on-topic
    • Include guardrails to prevent users from repurposing the Digital Twin for unrelated queries
Public-facing Digital Twins are inherently more vulnerable to abuse. Users may attempt to exploit the credit system or use the AI for purposes beyond its intended scope.

Integration

Choose the integration approach that matches your JavaScript skill level and requirements — Limited embeds the UI with minimal code, the Starter Kit ships two ready-to-use examples, and Standard gives you full programmatic control.
Embed the Digital Twin UI in your website header with:
The pria-sdk-web.js file is the SDK you downloaded. Optionally, place this in a directory, e.g., /assets/js/pria-sdk-web.js.
Basic initialization for DOM-ready load:
Adjust parameters in the SDK for your Digital Twin, user identity, and display preferences:
For security, retrieve these values from a secure, asynchronous source to avoid exposing sensitive data.

Configuration Parameters

The SDK requires three objects: displayOptions, instanceConfig, and userConfig.

Display Options

The displayOptions object controls the display and behavior of your digital twin on screen.
Set noUI: true to use Pria programmatically without the visual interface
Adjust buttonPositionRight with CSS for positioning, e.g., calc(50% - 40px) for center alignment.

Convo Mode (convoMode)

The convoMode display option lets you auto-start real-time voice (speech-to-speech) mode as soon as the Digital Twin determines that voice is available for the current user. This is useful when you want your application to launch directly into a voice experience without requiring the user to navigate through the text interface first. How it works: After the user authenticates, the SDK receives a convo.ready event from the Digital Twin indicating whether real-time voice is authorized. When convoMode is enabled, the SDK automatically sends a convo.start command and opens the UI panel. Values: Simple auto-start:
Targeted auto-start with a specific assistant and conversation:
convoMode requires that real-time voice (convo) is enabled for the user’s institution. If voice is not authorized, the flag is silently ignored and the text interface loads normally.

Assistant pre-select (assistantId)

Open the embedded Digital Twin in normal text mode with a specific assistant already selected — no opening message is injected, and the user’s first typed message is routed to that assistant.
How it works: once the session is ready, the SDK sends a single assistant.select command. The chat shows the assistant as the pending choice; the conversation itself is only created when the user sends their first message, which carries the selection. After that first exchange the conversation keeps the assistant automatically.
  • Works for text-only institutions — voice does not need to be enabled.
  • If both assistantId and convoMode are supplied, convoMode (voice) takes precedence and the text-mode pre-select is skipped — including when voice turns out not to be authorized for that institution, in which case neither applies and the twin opens normally. Supply only assistantId if you want the pre-select to be the fallback.
  • An unknown or out-of-scope assistantId is rejected with an error response and the twin opens on its normal default assistant.
  • The pre-select fires once per session; if the user manually switches assistants afterwards, their choice is never overridden.

Voice transcripts (transcripts)

Set transcripts: true to receive the conversation’s live transcript (convo.transcript messages) on your page while a voice call runs. The Digital Twin must allow it (Share voice transcripts with the embedding page in its settings); otherwise the option is silently ignored. See Live voice transcripts.

Instance Configuration

The instanceConfig object configures which Digital Twin to use along with the picture rendered in the start button.
The publicId value supports three modalities: Leave pictureUrl empty for Pria’s default picture, or point it to a CORS-accessible image on a CDN.
Load these values securely and asynchronously—never expose sensitive data in your HTML.

User identity

Set the user identity in the userConfig object
The email is required and serves as the main identifier in Praxis AI Middleware.
For education, set roleid and rolename to specify the course.
Use partnerid and partnername to identify an Account or Customer when you create a multi tenant solution
For enhanced security, always retrieve these values asynchronously from a secure source to prevent exposure of plaintext data in the page.

Wait for Pria and Start Convo mode

Here is an example demonstrating how to Wait for Pria to be fully ready, then start Convo mode
Use window.pria.isReady() to check if Pria is fully initialized before sending commands.

Integration Class Sample

This example is provided AS IS to demonstrate how you can cleanly integrate a Digital Twin in your Web Application. It is extracted from the playground example code.

Key SDK Methods Used

Checking Ready State

Always verify Pria is ready before sending commands:
The isReady() method returns true only when the SDK is fully connected to the middleware and ready to send/receive messages.

Cleanup and Reload

When you need to remove Pria or reload it with new configuration:
After calling destroy() or destroySdk(), all existing references to pria become invalid. The SDK must be fully reloaded before use.

SDK Playground Example

See a live demo: at SDK Playground Example.
SDK Playground Example This demo covers integration, connection detection, command execution, and more.

Automation

Refer to the Javascript APIs for interacting with your Digital Twin programmatically using Javascript