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; Widget Setup installs it.

Script-tag loader

For non-React sites, the script-tag loader needs no package install and passes through every mtx-* attribute.

Script-tag attributes

Attribute	Type	Description
mtx-id	string	Your Widget ID.
mtx-key	string	Your Widget Key.
mtx-api-host	string	API server URL, e.g. https://api.marketrix.ai.
mtx-use-screenshare	boolean	Set to "false" to auto-deny screen-access requests and hide the Share Screen button.
mtx-style-nonce	string	A CSP nonce applied to the widget’s injected <style> element. Needed only if your style-src policy has no 'unsafe-inline'.

mtx-id, mtx-key and mtx-api-host are all required — there is no default API host, and the widget refuses to initialize without one.

Functions

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

mountWidget(config)

declare function mountWidget(config: AddWidgetConfig): Promise<void>;

The entry point for programmatic use. It picks the mode from the config — mtxId + mtxKey + mtxApiHost for production, settings for a non-networked preview — and throws if neither combination is present. The container is a key of the config object, not a second argument; omit it and the widget mounts to the page body.

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

const credentials = {
  mtxId: 'YOUR_WIDGET_ID',
  mtxKey: 'YOUR_API_KEY',
  mtxApiHost: 'https://api.marketrix.ai',
};

// Production
await mountWidget(credentials);

// Production, mounted into a specific element
await mountWidget({ ...credentials, container: document.getElementById('my-container')! });

// Preview — renders the appearance you pass, and makes no network calls. `settings` is the
// full WidgetSettingsData shape; there is no partial form, so every key below is required.
await mountWidget({
  settings: {
    widget_enabled: true,
    widget_appearance: 'default',
    widget_position: 'bottom_right',
    widget_header: 'Marketrix AI',
    widget_body: 'How can I help you today?',
    widget_greeting: 'Hey There!',
    widget_greeting_toast: true,
    widget_recording: false,
    widget_feature_tell: true,
    widget_feature_show: true,
    widget_feature_do: true,
    widget_background_color: '#f5f5f5',
    widget_text_color: '#6B6B6B',
    widget_border_color: 'rgba(255, 255, 255, 0.3)',
    widget_accent_color: '#303030',
    widget_secondary_color: '#707070',
    widget_border_radius: '12px',
    widget_font_size: '14px',
    widget_width: '360px',
    widget_height: '450px',
    widget_animation_duration: '300ms',
    widget_fade_duration: '200ms',
    widget_chips: [],
  },
});

initWidget(config, container?)

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

The production half of mountWidget, reachable on its own: it validates credentials, fetches widget settings from the API, mounts the widget, and starts Session recording. It has no preview mode, and it is the one function that takes the container as a second argument. 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.

updateMarketrixConfig(newConfig)

declare function 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.

getCurrentConfig()

declare function getCurrentConfig():
  | (ClientOwnedConfig &
      Omit<WidgetSettingsData, 'widget_border_radius' | 'widget_font_size' | 'widget_animation_duration' | 'widget_fade_duration'> & {
        mtxId?: string;
        mtxKey?: string;
        isPreviewMode: boolean;
      })
  | null;

Returns the resolved configuration the widget is rendering — your client-owned keys and credentials merged with the dashboard settings — or null if the widget isn’t initialized. The type is not exported under a name.

unmountWidget()

declare function unmountWidget(): void;

Destroys the widget, stops Session recording, and removes the widget container.

Note

Session recording has no separate start/stop functions. It is driven entirely by the widget_recording dashboard setting — Session recording begins automatically once the widget starts its conversation, and unmountWidget() stops it.

React component (preview mode)

declare const MarketrixWidgetPreview: React.FC<MarketrixWidgetPreviewProps>;

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 { MarketrixWidgetPreview, type WidgetSettingsData } from '@marketrix.ai/widget';

// `settings` is the same full WidgetSettingsData shape as mountWidget's preview mode above —
// every key is required, there is no partial form.
declare const settings: WidgetSettingsData;

function Preview() {
  return <MarketrixWidgetPreview settings={settings} />;
}

MarketrixWidgetPreviewProps

Prop	Type	Description
settings	WidgetSettingsData	Widget settings to render (required).
container	HTMLElement	Optional element to mount into; defaults to the component’s own div.

Configuration

Both entry points carry the same client-owned keys, ClientOwnedConfig. They differ in how credentials arrive and where the container goes.

Key	Type	Description
widget_position_z_index	number	Stacking order. Raised to the widget’s own layer (2147483002) if you pass anything lower, so it can only move the widget higher.
show_widget	boolean	When false, the widget initializes fully but its UI is hidden. Default true. Hides on top of the dashboard’s own widget_enabled/widget_appearance settings below — it can only add a reason to hide, never override a dashboard setting that already hides the widget.
use_screenshare	boolean	When false, screen-access requests are auto-denied and the Share Screen button is hidden. Default true.
styleNonce	string	A CSP nonce applied to the widget’s injected <style> element (mtx-style-nonce for the script tag). Needed only if your style-src policy has no 'unsafe-inline'.

AddWidgetConfig — what mountWidget takes

Those keys, an optional container: HTMLElement, and exactly one credential shape — the type rejects both at once:

• Production — mtxId, mtxKey and mtxApiHost (the API server URL, with no default), required together.
• Preview — settings: WidgetSettingsData, nested under that one key, on its own.

MarketrixConfig — what initWidget takes

Those keys plus mtxId, mtxKey and mtxApiHost, all required. It carries no appearance keys: appearance is set in the dashboard, or through settings on mountWidget’s preview mode and MarketrixWidgetPreview.

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 mode.

Key	Type	Notes
widget_enabled	boolean	false aborts initialization entirely — no conversation, no stream, no Session recording. Unlike widget_appearance/show_widget below, the widget never mounts.
widget_appearance	'default' | 'hidden'	hidden keeps the widget initialized but suppresses its UI on the host page.
widget_position	'bottom_left' | 'bottom_right' | 'top_left' | 'top_right'	Corner placement.
widget_header	string	Header title.
widget_body	string	Intro/body text.
widget_greeting	string	The widget’s first message.
widget_greeting_toast	boolean	Wave a hand at the launcher shortly after it appears. Independent of the greeting message in chat.
widget_recording	boolean	Enable Session recording. Off by default.
widget_feature_tell	boolean	Enable Tell mode.
widget_feature_show	boolean	Enable Show mode.
widget_feature_do	boolean	Enable Do mode.
widget_background_color	string
widget_text_color	string
widget_border_color	string
widget_accent_color	string
widget_secondary_color	string
widget_border_radius	string	Rendered from the widget’s own constants — not writable via the dashboard, but required in a preview settings object.
widget_font_size	string	Rendered from the widget’s own constants — not writable via the dashboard, but required in a preview settings object.
widget_width	string
widget_height	string
widget_animation_duration	string	Rendered from the widget’s own constants — not writable via the dashboard, but required in a preview settings object.
widget_fade_duration	string	Rendered from the widget’s own constants — not writable via the dashboard, but required in a preview settings object.
widget_chips	WidgetChip[]	Quick-action chips.

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

Note

In production, widget_appearance: 'hidden' and show_widget: false are ORed, not ranked — either one hides the widget’s UI, and neither can override the other. In particular, show_widget: true cannot un-hide a widget the dashboard has hidden. Preview mode evaluates neither, so this only applies once the widget is live.

Next steps

Testing WidgetVerify the integration you just wired up against your real application.

Widget CustomizationConfigure the same settings this API's WidgetSettingsData controls.