API Reference

Every React prop, web-component attribute and event, loader attribute and action, and postMessage type

The complete embed surface across every delivery mode. For installs and examples, see Install.

The framework packages (React, Vue, Angular, Ember) all wrap the same Web Component below, so they share the same attributes and events under idiomatic names (props/emits, @Input/@Output, {{on}}). React props are documented here; the per-framework install pages list each framework's exact names.

React Component Props

import { WexioWidget } from "@wexio/messenger-widget-react";

Prop	Type	Purpose
`publicKey`	`string`	Integration key. Omit for demo mode.
`user`	`VisitorIdentity`	Known-visitor proof. Memoise it.
`config`	`InjectableWidgetConfig`	Pre-resolved config; skips the bootstrap fetch.
`theme`	`"light" \| "dark" \| "auto"`	Force the widget theme. Reactive. Wins over the dashboard default and the visitor's system setting.
`configOverride`	`Partial<WidgetConfig>`	Presentation fields merged over the saved config. See Overrides.
`defaultOpen`	`boolean`	Open the panel on mount. After that the visitor can close it.
`open`	`boolean`	Controlled open state. A change of value opens or closes the panel. Keep it in sync from `onOpen` and `onClose`. Omit it for an uncontrolled widget.
`previewTab`	`{ tab, nonce, article? }`	Go to a tab (`home`, `messages`, `help`, `news`, `profile`), or to a help article `{ kind: "help", slug }` or news post `{ kind: "news", id }`, and open the panel. A new `nonce` repeats the request.
`offset`	`{ x?: number; y?: number }`	Move the launcher and panel away from their corner, in px (`x` inward from the side, `y` up from the bottom). Each axis is clamped to 0-200.
`onResize`	`(size: { width: number; height: number }) => void`	Panel dimensions changed.
`onOpen`	`() => void`	Panel opened (launcher, message bubble).
`onClose`	`() => void`	Panel closed. Fires on every close: the header close button, the launcher and the `Escape` key.
`onMessageAction`	`(event) => void`	A visitor clicked a quick reply on a welcome message. `event` has `slotId`, `variantId`, `buttonId`, `actionType` (`QUICK_REPLY`) and `source` (`WELCOME`).
`className`	`string`	Outer host element class.
`style`	`React.CSSProperties`	Outer host element styles.

Web Component

Element: wexio-widget (registered by https://cdn.wexio.io/widget/widget.js).

Attributes (observed live)

Attribute	Purpose
`public-key`	Integration key.
`locale`	Force a UI locale (BCP-47).
`prefill-name` / `prefill-email` / `prefill-phone`	Unverified prechat prefill.
`theme`	`"light"`, `"dark"` or `"auto"`. Forces the widget theme. Reactive.
`open`	`"true"` or `"false"`. Controlled open state: a change opens or closes the panel. Leave it off for an uncontrolled widget.
`default-open`	`"true"` opens the panel on mount. Read once at mount.
`offset-x` / `offset-y`	Launcher offset in px, as for the React `offset` prop.

Property and Method

element.previewTab = { tab: "help", nonce: 1 };  // go to a tab and open the panel

element.identify(user: VisitorIdentity | null): void;  // null = log out

Events

Event	`detail`	When
`wexio:resize`	`{ width, height }`	Panel resized.
`wexio:open`	-	Panel opened.
`wexio:close`	-	Panel closed (header close button, launcher or `Escape`).
`wexio:message-action`	`{ slotId, variantId, buttonId, actionType, source }`	A visitor clicked a quick reply on a welcome message.

The events bubble and cross the shadow boundary. With the script loader they are dispatched on window, for example window.addEventListener("wexio:open", ...).

Loader Script

<script src="https://cdn.wexio.io/widget/loader.js" data-public-key="pk_live_..."></script>

Data Attributes

Attribute	Default	Purpose
`data-public-key`	required	Integration key.
`data-origin`	`https://cdn.wexio.io`	Widget CDN base.
`data-api`	`https://api.wexio.io`	Backend API base.
`data-hide-attribution`	-	Ignored. The loader never shows an attribution link to visitors.

`window.Wexio(action, …)`

Action	Argument	Effect
`"identify"`	`VisitorIdentity \| null`	Log a known visitor in / out.
`"prefill"`	`{ name?, email?, phone? }`	Update prechat prefill.
`"shutdown"`	-	Clear identity, start fresh anonymous session.
`"theme"`	`"light" \| "dark" \| "auto"`	Switch the widget theme at runtime, for example from your own dark-mode toggle.
`"show"`	-	Show the iframe.
`"hide"`	-	Hide the iframe.
`"open"` / `"close"`	-	Open or close the panel.
`"navigate"`	`{ tab, article? }`	Go to a tab, or to a help article `{ kind: "help", slug }` or news post `{ kind: "news", id }`, and open the panel.

open, close and navigate are one-shot commands. Calls made before the widget is ready are queued and run when it is. Closing the panel never hides the launcher. Use "hide" for that.

`VisitorIdentity`

interface VisitorIdentity {
  // Provide exactly one proof (precedence: googleIdToken → jwt → userId+userHash):
  googleIdToken?: string;
  jwt?: string;
  userId?: string;
  userHash?: string;
  // Optional profile on any path:
  name?: string;
  email?: string;
  phone?: string;
  attributes?: Record<string, unknown>;
}

See Authentication.

Pre-boot settings

interface Window {
  wexioSettings?: {
    user?: VisitorIdentity;
    prefill?: { name?: string; email?: string; phone?: string };
    config?: InjectableWidgetConfig;
    configOverride?: Partial<WidgetConfig>;   // presentation patch, see Overrides
    theme?: "light" | "dark" | "auto";        // script loader: initial theme
    defaultOpen?: boolean;                    // script loader: open the panel once ready
    offset?: { x: number; y: number };        // script loader: launcher offset in px
  };
}

Overrides

configOverride (the React prop and wexioSettings.configOverride) may change presentation only: theme, themeMode, features, defaultTab, greeting, prechatForm, sounds, messenger and similar. The widget drops status, branding and integrationId, and keeps only google.enabled and passkey.enabled from security. Plan limits and requireAuth stay with the server.

postMessage protocol

The iframe loader and the widget communicate over versioned postMessage types. You don't normally call these directly - they're listed for debugging.

Loader → widget:

Type	Payload
`wexio:identify:v1`	`{ user: VisitorIdentity }`
`wexio:prefill:v1`	`{ prefill }`
`wexio:shutdown:v1`	-

Widget → loader:

Type	Payload
`wexio:widget:ready:v1`	-
`wexio:widget:open:v1`	-
`wexio:widget:close:v1`	-
`wexio:widget:resize:v1`	`{ width, height }`

Bootstrap endpoints

Endpoint	Purpose
`GET /api/web/config/:publicKey`	Full sanitised widget config.
`GET /api/web/config/:publicKey?view=gate`	Slim pre-mount payload (`status`, `branding.hidden`, `security`).
`POST /api/web/visitor/start-identified`	Identified handshake.
`POST /api/web/visitor/start-anonymous`	Anonymous handshake.
`GET /api/web/realtime/:chatId`	Server-sent events stream for live messages.

Script loader - the loader tag and its data attributes in context.
Config reference - the full widget option schema.
Authentication - what identify needs on the server side.

API Reference

On this page