Widget Embedding

Overview

The PromethistAI Widget allows you to embed Relational Agents directly into your website with a single script tag. The widget can appear as a floating assistant that users expand to interact with your agent, or it can be mounted into a container element you control.

Quick Start

Add one script tag and provide either data-region or data-url.

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

  • data-region accepts eu or us, based on your account location.

  • If data-url is provided, data-region is not required.

  • Auto-initialization happens only when autoInit !== false and either region or url is set.

  • Configuration priority is: defaults → window.PromethistWidgetConfig → script data-* attributes (later sources win).

Replace yourAgentRef with your agent’s unique identifier. To find it, use the Copy URL option and take the part at the end of the URL, after /a/. For example, in https://eu.promethist.ai/a/myAgentQsiqmy.0 the agent reference is myAgentQsiqmy.0. Plain values are normalized to the agent:…​ form automatically.

Using Draft Agents

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

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

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

  • Published agents use the reference 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.)

Setup Patterns

Use one of the following setup patterns based on how much control you need.

Hosted by Region

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

Custom URL

<script
  src="https://eu.promethist.ai/client/embedding/promethist-widget.js"
  data-url="https://eu.promethist.ai/client/?isEmbedded=true&key=agent%3AyourAgentRef"></script>

The URL must resolve to a valid absolute, non-opaque origin (for example, https://…​;).

Global Config Object

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

<script>
  window.PromethistWidgetConfig = {
    // region is required only when url is not set
    region: 'eu',
    // url: 'https://eu.promethist.ai/client/?isEmbedded=true&key=agent%3AyourAgentRef',
    agentRef: 'agent:yourAgentRef',
    showExpanded: false,
    showOnReady: true,
    autoInit: 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

Container Layout

Mount the widget into an element you control instead of floating it:

<div id="assistant-container" style="position: relative; width: 100%; height: 500px;"></div>

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

Configuration Reference

All supported configuration keys and their corresponding script attributes.

Config key Script attribute Default Notes

region

data-region

null

Required when url is not set. Allowed: eu, us.

url

data-url

null

If set, it is used directly and region is optional.

agentRef

data-agent-ref

null

Plain values are normalized to agent:…​.

showExpanded

data-show-expanded

false

Floating mode display preference.

showOnReady

data-show-on-ready

true

If false, widget remains hidden until explicit show/open.

contractTimeoutMs

data-contract-timeout-ms

1500

Positive integer.

expandReadyTimeoutMs

data-expand-ready-timeout-ms

12000

Positive integer.

collapseNoAckStrategy

data-collapse-no-ack-strategy

keep-expanded

Allowed: keep-expanded, hide, force-collapsed.

width, height

data-width, data-height

140px, 140px

Floating collapsed dimensions.

expandedWidth, expandedHeight

data-expanded-width, data-expanded-height

400px, 600px

Floating expanded dimensions.

bottom, right

data-bottom, data-right

0px, 0px

Floating collapsed position.

expandedBottom, expandedRight

data-expanded-bottom, data-expanded-right

20px, 20px

Floating expanded position.

zIndex

data-z-index

9999

Applied as a CSS variable.

allowMicrophone

data-allow-microphone

true

Controls iframe allow permissions.

allowCamera

data-allow-camera

true

Controls iframe allow permissions.

autoInit

data-auto-init

true

If false, call init() yourself.

skipCollapsedOnFirstOpen

data-skip-collapsed-on-first-open

false

Only meaningful for floating mode first-open behavior.

layoutMode

data-layout-mode

floating

Allowed: floating, container.

container

data-container

null

Required when layoutMode="container". An HTMLElement or selector.

Boolean parsing rule: any provided value except the literal "false" is treated as true.

JavaScript API

Initialization rule: default-instance methods do not auto-create an instance. Call PromethistWidget.init() first unless auto-init has already run.

Static API

// Properties
PromethistWidget.version;
PromethistWidget.state;
PromethistWidget.instances;

// Methods
const widget = PromethistWidget.create({ region: 'eu', agentRef: 'agent:demo' });
const sameWidget = PromethistWidget.getInstance(widget.id);

PromethistWidget.init(overrides?);
PromethistWidget.open({ skipCollapsedOnFirstOpen?: boolean }?);
PromethistWidget.show({ expanded?: boolean }?);
PromethistWidget.setAgentRef('agent:anotherRef');
PromethistWidget.setAgentRef({ agentRef: 'agent:anotherRef' });
PromethistWidget.setExpanded(true);
PromethistWidget.expand();
PromethistWidget.collapse();
PromethistWidget.hide();
PromethistWidget.destroy();
PromethistWidget.clear();

const off = PromethistWidget.on('promethist:ready', (event) => {
  console.log(event.detail.instanceId);
});
off();

Instance API

const widget = PromethistWidget.create({
  region: 'eu',
  agentRef: 'agent:yourAgentRef',
  autoInit: false
});

widget.id;
widget.state;
widget.config;

widget.init({ showOnReady: false });
widget.open({ skipCollapsedOnFirstOpen: true });
widget.show({ expanded: true });
widget.setAgentRef('agent:newAgentRef');
widget.setExpanded(true);
widget.expand();
widget.collapse();
widget.hide();
widget.destroy();
widget.clear();
widget.on('promethist:warning', (event) => console.warn(event.detail.code));

Layout caveat: setExpanded/expand/collapse operate only in floating mode. In container mode, hiding/showing is the relevant visibility control.

Events, Warning Codes, and States

All events are dispatched on document.

Event Detail payload When emitted

promethist:ready

{ instanceId }

Iframe reports widget ready.

promethist:open

{ instanceId }

Widget opens to expanded scene.

promethist:hidden

{ instanceId }

Widget is hidden.

promethist:destroyed

{ instanceId }

Widget instance is destroyed.

promethist:statechange

{ from, to, reason, instanceId }

Internal state transition.

promethist:warning

{ code, message, instanceId, …​extra }

Capability mismatches, timeouts, or invalid transitions.

Warning Codes

  • SCENE_READY_TIMEOUT

  • MISSING_COLLAPSE_CAPABILITY

  • COLLAPSE_ACK_TIMEOUT

  • MISSING_UPDATE_AGENT_CAPABILITY

  • INVALID_STATE_TRANSITION

States

  • idle

  • loading

  • collapsed

  • expanded

  • hidden

  • destroyed

Lifecycle and No-op Rules

The typical lifecycle is:

create() -> init() -> show()/open()/setExpanded() -> hide()/collapse() -> destroy()

  • init(): only works in idle; no-op otherwise.

  • open(): works in collapsed/hidden; queues while loading.

  • show(): no-op if iframe is not initialized. In floating mode, may collapse or open expanded based on config/options.

  • hide(): no-op if iframe is not initialized; transitions to hidden.

  • setExpanded(true): floating mode only, routed through open().

  • setExpanded(false): floating mode only, requests collapsed icon state.

  • setAgentRef(): queues while loading, updates live in collapsed/expanded/hidden.

  • destroy(): always removes the iframe and transitions to destroyed.

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 data-region (or data-url) — one of them is required

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

  • showOnReady set to false without a subsequent explicit show()/open() call

  • autoInit set to false without calling init() yourself

  • WebGPU not supported by the browser

  • JavaScript errors blocking widget initialization

Container Mode Issues

  • data-container must point to an existing element (an HTMLElement or a valid selector)

  • The container element should establish its own size and positioning context (for example, position: relative with an explicit height)