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-agent | number | Agent 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 + mtx-agent (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 + mtxAgent.

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). | | mtxAgent | number | Agent 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 + mtxAgent (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 | Agent’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()