Web Component

Embed the widget as a custom element - attributes, events, and the identify() method

The Web Component embed registers a wexio-widget custom element backed by Shadow DOM. It works in any framework, including Vue, Angular, and Svelte, and in plain HTML.

Basic Usage

Load the module once, then place the element anywhere in your markup:

<script type="module" src="https://cdn.wexio.io/widget/widget.js"></script>

<wexio-widget public-key="pk_live_..."></wexio-widget>

Attributes

The element observes these attributes live. Changing one re-resolves the config without unmounting the widget:

Attribute	Default	Behaviour
`public-key`	-	Your widget's public key. Omit or leave empty for the demo fallback.
`locale`	auto	Force a UI locale (a BCP-47 code). Overrides the operator's locale strategy. See Localization.
`mode`	auto	Set `"demo"` to show bundled sample content and ignore `public-key`. Leave it off for a live widget.
`prefill-name`	-	Unverified prechat prefill.
`prefill-email`	-	Unverified prechat prefill.
`prefill-phone`	-	Unverified prechat prefill.
`theme`	-	`"light"`, `"dark"` or `"auto"`. Forces the widget theme. Change it when your site switches theme and the widget follows.
`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.
`offset-x`, `offset-y`	-	Move the launcher away from its corner, in px.

<wexio-widget public-key="pk_live_..." locale="pt-BR"></wexio-widget>

Events

The element dispatches custom events. They bubble and cross shadow boundaries:

Event	`event.detail`	When
`wexio:resize`	`{ width, height }`	The panel's dimensions changed.
`wexio:open`	-	The panel opened.
`wexio:close`	-	The 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.

el.addEventListener("wexio:resize", (e) => {
  console.log("panel size", e.detail.width, e.detail.height);
});

To go to a tab or article and open the panel, set the element's previewTab property. A new nonce repeats the request:

el.previewTab = { tab: "help", nonce: 1 };

Identifying a Visitor

To identify a visitor, call the element's identify() method with a VisitorIdentity. Pass null to log out:

const el = document.querySelector("wexio-widget");

el.identify({ jwt: "<host-signed-jwt>", name: "Ada Lovelace" });

// later, on logout:
el.identify(null);

See Authentication for how to produce the proof.

Pre-Boot Settings

To pass identity, prefill, or a pre-resolved config before the element mounts, set window.wexioSettings:

<script>
  window.wexioSettings = {
    user: { jwt: "<host-signed-jwt>", name: "Ada" },
    config: { /* InjectableWidgetConfig - skips the bootstrap fetch */ },
    configOverride: { /* Partial config merged over the saved one, e.g. theme or greeting */ },
  };
</script>
<script type="module" src="https://cdn.wexio.io/widget/widget.js"></script>
<wexio-widget public-key="pk_live_..."></wexio-widget>

configOverride is a partial config merged over the resolved one. Use it to brand the widget from your page without supplying a full config. Passing a config object skips the GET /api/web/config/:pk bootstrap fetch. Use it when you already have the config server-side. See the config reference.

Try It Live

The examples repo has a runnable zero-build example. You can also configure the widget live in the Playground.

React component - the package for React hosts.
Localization - pin and switch languages.
Authentication - produce identity proofs.
Examples - runnable apps for every framework.