Skip to main content
One thing, three names. In these docs we call your assistant a Digital Twin. You will also see it called an Instance — on the Instance Settings panel, in the admin Instances list, and in your web address (your-instance.praxislxp.com) — and an Institution, which is what our software calls it behind the scenes (in API fields such as institution). All three mean exactly the same thing: one assistant, with its own knowledge, voice, members and settings. Which name you see depends on the screen you are on, not on what the thing is. An Account is different — it is the organisation that owns one or more Digital Twins.

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 above the admin Instances List and pick which Digital Twin to generate code for.
To open Instance Settings from a conversation, open the + options menu in the message bar, choose Settings, then the row with your Digital Twin’s picture and name (it reads Instance when the twin has no AI name), and select the Integration screen. Every screen of that panel is described in Instance Settings.
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 your Digital Twin's row 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). Show advanced options adds Allow pop-out, Headless (no UI) and custom container IDs. Headless loads the twin with no visible panel, for pages whose own code drives it. Don’t use it when the Digital Twin’s account asks people to accept a privacy policy: without the panel nobody can accept it, and the twin will not answer.
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 once your site is allowed (next section). Above the code, the wizard shows the sites this Digital Twin accepts.
Integration wizard code step showing the generated snippet with copy and save controls.

Preview the generated code, then copy or download it.

Allow your site first

The web page, React, Flask and Canvas code only starts on a site listed in the Digital Twin’s Public Authorized URLs. On any other site, Pria refuses to open, and the browser console shows Pria SDK: Failed to sign launch parameters Unauthorized origin.
Before you paste the code, add the address of each site that will run it:
  • A website or app: its address, such as https://www.example.edu. An entry also covers the site’s subdomains.
  • Canvas: your Canvas address, such as https://school.instructure.com.
  • The Flask app on your own computer: http://localhost as well, while you try it.
The list is in the Digital Twin’s full editor, under Integrations — see Public Authorized URLs. The generated file repeats this requirement at the top, and the wizard warns you when the list is empty. The avatar widget has its own rule on its page, and the Claude target calls the API directly, so it needs no entry.

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 (kept in a cookie) — no sign-in required. Dormant guests are cleaned up automatically, except on a Digital Twin that pools credits, where they accumulate (the wizard warns you). Ideal for public, anonymous embeds.
  • Off: the generated code leaves a clearly marked gap where you plug in your own sign-in, so you can pass real user details (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 created at pria.praxislxp.com
  • Your Digital Twin’s Public ID (shown with a copy button in Instance Settings → General)
  • HTTPS enabled on your website (required for secure SDK communication)
  • Your site’s address added to Public Authorized URLs in the Digital Twin’s settings — every embed needs it, not only public twins (see Allow your site first)
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 (in the Digital Twin’s editor)
    • Turn off Pool Credits, so each guest spends their own credits instead of the twin’s shared balance
    • Set Credits Awarded to New Users to a small amount (e.g., 50 credits)
    • Turn on Guest UI (Minimum screen) for anonymous access
    • Turn off Use Location to prevent unwanted pop-ups
  2. Access Control
    • Add your domain (e.g., https://your-domain.com) to the list of Public Authorized URLs
    • Only domains in this list will be able to embed and access the Digital Twin
  3. Tool Restrictions
    • In Instance Settings → Tools, keep only the tools guests need (the Minimal preset is a good start) and turn off tools that act on the outside world, such as call_rest, send_email, call_canvas and save_to_file
    • 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 on this Digital Twin. 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 Digital Twins — 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 on that Digital Twin, 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.

Confirm it’s you (onAuthRequired)

When an admin account opens Pria from your page (for example a Canvas course page), Pria may first show Confirm it’s you inside its panel and ask for a 6-digit code. Until the person enters it, Pria refuses commands. The SDK calls your onAuthRequired function once, so you can bring the panel into view:
If you hide the launcher (noUI, a hidden button container, or setVisible(false)), you must handle this — call window.pria.setVisible(true) and then display(true), or tell the person where to confirm — or nobody can reach the code screen. See Confirm it’s you for how commands behave meanwhile.

Digital Twin configuration (instanceConfig)

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