Widget Embedding

Overview

The PromethistAI Widget allows you to embed Relational Agents directly into your website with a simple script tag. The widget appears as a floating assistant that users can expand to interact with your agent.

Basic Integration

Minimal Setup

Add this single line to your HTML page:

<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js" data-region="eu"></script>

The data-region parameter is required and must be either eu or us based on your account location.

With Agent Key

Specify your region and agent key using data attributes:

<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js"
        data-region="eu"
        data-agent-key="agent:yourAgentKey"></script>

Replace yourAgentKey with your agent’s unique identifier. You can find it by copying the identifier shown below the button Open URL (e.g., @eli).

Using Draft Agents

If your agent is not published and still in draft status, you need to append the draft number to the agent key:

<!-- For Draft-0 -->
<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js"
        data-region="eu"
        data-agent-key="agent:yourAgentKey.0"></script>

<!-- For Draft-1 -->
<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js"
        data-region="eu"
        data-agent-key="agent:yourAgentKey.1"></script>

  • Published agents use the key as-is: agent:eli

  • Draft agents require the draft number: agent:eli.0, agent:eli.1, etc.

  • The draft number corresponds to the version shown in the Platform (Draft-0, Draft-1, etc.)

Configuration Options

Using Data Attributes

Customize the widget appearance and behavior directly in the script tag:

<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js"
        data-region="eu"
        data-agent-key="agent:yourAgentKey"
        data-width="140px"
        data-height="140px"
        data-expanded-width="400px"
        data-expanded-height="600px"
        data-fade-in-delay="1000"></script>

Available Configuration Parameters

Parameter Description Default

data-region

Server region (eu or us) – Required

None

data-agent-key

Your agent’s unique identifier (use .0, .1 suffix for drafts)

None

data-width

Widget width when collapsed

140px

data-height

Widget height when collapsed

140px

data-expanded-width

Widget width when expanded

400px

data-expanded-height

Widget height when expanded

600px

data-fade-in-delay

Delay before widget appears (milliseconds)

1000

data-allow-microphone

Enable microphone access for voice interaction

true

data-allow-camera

Enable camera access for video interaction

true

Advanced Configuration

Global Configuration Object

For more control, set configuration globally before loading the script:

<script>
  window.PromethistWidget = {
    region: 'eu',              // Required: 'eu' or 'us'
    agentKey: 'agent:yourAgentKey',  // Use 'agent:key.0' for drafts
    width: '140px',
    height: '140px',
    expandedWidth: '400px',
    expandedHeight: '600px',
    fadeInDelay: 1000,
    allowMicrophone: true,
    allowCamera: true
  };
</script>
<script src="https://eu.promethist.ai/client/embedding/promethist-widget.js"></script>

This approach is useful when you need to:

  • Dynamically generate configuration values

  • Integrate with existing JavaScript frameworks

  • Apply conditional logic to widget settings

JavaScript API

Programmatic Control

Control the widget programmatically using the JavaScript API:

// Expand the widget
PromethistWidget.expand();

// Collapse the widget
PromethistWidget.collapse();

// Toggle between expanded and collapsed states
PromethistWidget.toggle();

// Hide the widget completely
PromethistWidget.hide();

// Show the widget after hiding
PromethistWidget.show();

Technical Requirements

The widget inherits the same technical requirements as the Web Client:

  • WebGPU support in the browser

  • Microphone permissions for voice interaction

  • Modern browser (Chrome, Edge, Safari with WebGPU)

See Web Client Technical Requirements for detailed browser compatibility information.

Troubleshooting

Widget Not Appearing

Check the browser console for errors. Common issues include:

  • Missing or invalid data-region parameter

  • Invalid agent key (verify you’re using the correct format for draft agents)

  • WebGPU not supported by the browser

  • JavaScript errors blocking widget initialization