Widget API Reference

The widget ships as the npm package @marketrix.ai/widget. Use it when you need programmatic control over the widget lifecycle. React 19 is a peer dependency.

npm install @marketrix.ai/widget

Script-tag install

For non-React sites, the classic loader needs no package install. The loader.js script injects the React import map, loads the widget bundle from the same origin, and passes through every mtx-* attribute.

<script
  src="https://widget.marketrix.ai/loader.js/loader.js"
  mtx-id="YOUR_WIDGET_ID"
  mtx-key="YOUR_API_KEY"
  mtx-api-host="https://api.marketrix.ai"
></script>

Place the loader in the page <head>, before any other <script type="module"> tags.

Script-tag attributes

Attribute	Type	Description
`mtx-id`	string	Your Widget ID (production mode).
`mtx-key`	string	Your Widget Key (production mode).
`mtx-app`	number	Application ID (dev mode).
`mtx-api-host`	string	API server URL, e.g. `https://api.marketrix.ai`.

Provide either mtx-id + mtx-key (production) or mtx-app (dev).

Functions

All functions are named exports of @marketrix.ai/widget.

`initWidget(config, container?)`

initWidget(config: MarketrixConfig, container?: HTMLElement): Promise<void>

Validates credentials, fetches widget settings from the API, mounts the widget, and starts session recording. If container is omitted, the widget mounts to the page body. Concurrent and duplicate calls are deduplicated via a window-level singleton guard, so calling it twice is safe.

import { initWidget } from '@marketrix.ai/widget';

// Production
await initWidget({
  mtxId: 'YOUR_WIDGET_ID',
  mtxKey: 'YOUR_API_KEY',
  mtxApiHost: 'https://api.marketrix.ai',
});

// Mount into a specific container
await initWidget(config, document.getElementById('my-container')!);

`mountWidget(config)`

mountWidget(config: AddWidgetConfig): Promise<void>

Auto-detects the mode from the config and initializes the widget:

Preview — settings provided directly (no network calls).
Production — mtxId + mtxKey.
Dev — mtxApp.

Throws if none of those combinations is present.

`updateMarketrixConfig(newConfig)`

updateMarketrixConfig(newConfig: Partial<MarketrixConfig>): Promise<void>

Merges newConfig into the current configuration, then unmounts and reinitializes the widget. No-op if the widget isn’t initialized; throws if the current config can’t be read.

`getCurrentConfig()`

getCurrentConfig(): MarketrixConfig | null

Returns the active widget configuration, or null if the widget isn’t initialized.

`unmountWidget()`

unmountWidget(): void

Destroys the widget, stops session recording, and cleans up all resources including the live event stream.

`startRecording()`

startRecording(): Promise<void>

Starts session recording. Safe to call while an automatic start is already in flight — it awaits the pending start rather than creating a concurrent one. Throws if the recorder was never created (for example, when the widget was initialized without mtxApiHost and an application ID).

`stopRecording()`

stopRecording(): void

Stops session recording without unmounting the widget. Recording can be resumed later with startRecording().

`getRecordingState()`

getRecordingState(): boolean

Returns whether session recording is currently active.

React component (preview mode)

MarketrixWidget: React.FC<MarketrixWidgetProps>

Renders the widget into a parent container with its own Shadow DOM. Intended for preview/embedding inside a React app — it’s what the dashboard uses to render the live preview.

import { MarketrixWidget } from '@marketrix.ai/widget';

function Preview() {
  return (
    <MarketrixWidget
      settings={{ widget_enabled: true, widget_position: 'bottom_right' /* ...other settings */ }}
      mtxApiHost="https://api.marketrix.ai"
    />
  );
}

`MarketrixWidgetProps`

Prop	Type	Description
`settings`	`WidgetSettingsData`	Widget settings to render (required).
`container`	`HTMLElement`	Optional element to mount into; defaults to the component’s own div.
`mtxId`	string	Optional credential override.
`mtxKey`	string	Optional credential override.
`mtxApiHost`	string	Optional API host override.

Configuration: `MarketrixConfig`

MarketrixConfig is Partial<WidgetSettingsData> plus the fields below — so any dashboard setting (such as widget_position, widget_chips, or colors) can also be passed inline.

Key	Type	Description
`mtxId`	string	Widget ID (production mode).
`mtxKey`	string	Widget Key (production mode).
`mtxApp`	number	Application ID (dev mode).
`mtxApiHost`	string	API server URL.
`userId`	number	Optional user ID to associate with widget questions.
`widget_position_offset`	`{ x?: number; y?: number }`	Pixel offset from the chosen corner. Default `{ x: 20, y: 20 }`.
`widget_position_z_index`	number	Stacking order of the widget. Default `40`.
`show_widget`	boolean	When `false`, the widget initializes fully but its UI is hidden. Default `true`.
`use_screenshare`	boolean	When `false`, screen-access requests are auto-denied and the Share Screen button is hidden. Default `true`.
`isPreviewMode`	boolean	Marks the widget as a non-networked preview instance.

Provide either mtxId + mtxKey (production) or mtxApp (dev). All modes require mtxApiHost.

Settings keys: `WidgetSettingsData`

These are the dashboard-managed appearance and behavior settings. They’re returned by the API for a production widget and can be supplied inline in preview/dev mode.

Key	Type	Notes
`widget_enabled`	boolean	Master on/off.
`widget_appearance`	`'default' \| 'compact' \| 'full'`	Layout preset.
`widget_position`	`'bottom_left' \| 'bottom_right' \| 'top_left' \| 'top_right'`	Corner placement.
`widget_device`	`'desktop' \| 'mobile' \| 'desktop_mobile'`	Device visibility.
`widget_header`	string	Header title.
`widget_body`	string	Intro/body text.
`widget_greeting`	string	The widget’s first message.
`widget_feature_tell`	boolean	Enable Tell mode.
`widget_feature_show`	boolean	Enable Show mode.
`widget_feature_do`	boolean	Enable Do mode.
`widget_feature_human`	boolean	Enable human handoff.
`widget_background_color`	string
`widget_text_color`	string
`widget_border_color`	string
`widget_accent_color`	string
`widget_secondary_color`	string
`widget_border_radius`	string	e.g. `16px`.
`widget_font_size`	string
`widget_width`	string
`widget_height`	string
`widget_shadow`	string
`widget_animation_duration`	string
`widget_fade_duration`	string
`widget_bounce_effect`	boolean
`widget_chips`	`WidgetChip[]`	Quick-action chips.

A WidgetChip is { chip_mode: 'tell' \| 'show' \| 'do'; chip_text: string }.

Example: full lifecycle

import {
  initWidget,
  updateMarketrixConfig,
  startRecording,
  stopRecording,
  getRecordingState,
  unmountWidget,
} from '@marketrix.ai/widget';

// Initialize after the user logs in
await initWidget({
  mtxId: 'YOUR_WIDGET_ID',
  mtxKey: 'YOUR_API_KEY',
  mtxApiHost: 'https://api.marketrix.ai',
});

// Reposition based on app state
await updateMarketrixConfig({ widget_position: 'bottom_left' });

// Toggle recording
stopRecording();
console.log(getRecordingState()); // false
await startRecording();

// Tear down on logout
unmountWidget();

Widget API Reference

Script-tag install

Script-tag attributes

Functions

initWidget(config, container?)

mountWidget(config)

updateMarketrixConfig(newConfig)

getCurrentConfig()

unmountWidget()

startRecording()

stopRecording()

getRecordingState()