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 & behaviour

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 behaviour toggles.

Configure the widget's position, size and behaviour 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

You can choose Limited or Standard Integration based on your JavaScript skill level and requirements.

Limited Integration

Start your Digital Twin with minimal effort, leveraging the UI without programming.

Standard Integration

Integrate your Digital Twin securely with JavaScript code and take full control.

Limited Integration

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.

Integration Starter Kit

Download the Example Starter Kit to get started with two ready-to-use integration examples.

PriaIntegration Class

Easy Setup Text interface: Use the helper class for quick setup with minimal code.

Direct SDK Control

Intialize and start Convo Mode: Load the SDK directly for full control over events and behavior.

Integration Sample (integration-sample.html)

This example demonstrates using the PriaIntegration class from pria-sdk-web.js for a streamlined integration:
Best for: Quick integrations where you want the Digital Twin button to appear and let users click to start conversations naturally.

SDK Sample (sdk-sample.html)

This example loads the remote pria-sdk.js directly, giving you full control over events and conversation flow:
Best for: Advanced integrations requiring:
  • Custom loading indicators while connecting
  • Automatic conversation start on button click
  • Error handling with retry logic
  • Visibility control based on connection state
The SDK Sample hides the Digital Twin UI until the conversation is confirmed started, providing a smoother user experience with loading feedback.

Standard Integration

For full control, use JavaScript to configure and load the SDK. Configuration object example:
This object configures display, digital twin instance, and user identity.
Load the SDK:
The SDK file should be the copy you installed. You can organize includes under /assets/js/ as needed.
For a full example, see SDK Playground Example.

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.

Instance Configuration

The instanceConfig object configure which Digital Twin to use along with the picture rendered in the start button.
The publicId identifies your digital twin instance
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