Welcome to @wexio/messenger-widget-react 👋

Native React component for the Wexio web messenger. Renders inside a Shadow DOM portal for full style isolation — same WidgetShell runtime as the script-injected iframe and the <wexio-widget> web component. Same chat, same visitor identity, same backend; the only difference is where the React tree mounts.

🏠 Website 📚 Developer Docs

Features

The messenger is a full two-way support surface, not just a contact form:

• Conversations & threads — real-time chat with history, read receipts and delivery states, plus multi-topic threads so a visitor can keep several questions side by side.
• Rich messages — images and galleries (with a lightbox), GIFs, inline video, voice notes, and file / PDF attachments; AI replies cite their sources.
• Composer — rich-text editing, emoji and GIF pickers, file attachments, and an in-widget voice recorder.
• Home, Help & News — a configurable Home tab (team status, quick actions, help search, news), a searchable help center, and a news feed — all driven by the operator's dashboard.
• Identity — anonymous by default, or log a known visitor in with a Google, JWT, or HMAC proof.
• Resilient & offline-aware — an offline outbox queues sends, reactions, read-acks and profile changes and converges on reconnect; a dropped connection is shown in-thread.
• Themed & localized — follows the operator's brand theme (light / dark) and ships 33 UI locales; visitors can switch language in-widget.
• Demo mode — omit the public key to render a self-contained preview with bundled mock content (great for landing pages and Storybook).

📂 Description

• Features
• Installation
• Quick start
• Identifying users
• Props
• Bot protection (Cloudflare Turnstile)
• Methods
• Types
• SSR
• Browser support
• Troubleshooting
• Use with other frameworks
• Author
• License

Installation

yarn add @wexio/messenger-widget-react

or

npm install @wexio/messenger-widget-react

react >= 18 and react-dom >= 18 are peer dependencies — the widget uses the host's React tree.

Quick start

Import the package on every page that should display the messenger (or on a common component used by them) and render the component. This must be done on the client side.

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

export default function App() {
  return (
    <>
      {/* your app */}
      <WexioWidget publicKey="pk_live_..." />
    </>
  );
}

That's it — the widget mounts a floating launcher, handles its own theme/locale/state, and the operator dashboard sees the visitor immediately. The component manages its own lifecycle internally, so re-renders due to host DOM changes won't trigger a re-boot.

Identifying users

Pass a verified user to log a known visitor in (a known-user login / boot). Provide ONE proof — a Google FedCM id_token, a host-signed jwt, or the legacy userId + userHash HMAC pair:

<WexioWidget
  publicKey="pk_live_..."
  user={{
    jwt: serverSignedJwt, // host-signed identity token (recommended)
    name: "Ada Lovelace",
    email: "ada@example.com",
  }}
/>

Memoise user. Fresh object literals every render churn the env (the handshake is internally guarded against re-firing unless the proof actually changes, but it's tidier to avoid).

Props

Prop	Type	Description
publicKey	string	Wexio integration public key (pk_live_...). Omit to render in demo mode (bundled mock content for landing pages or Storybook).
user	VisitorIdentity	Verified identity. See Identifying users.
config	InjectableWidgetConfig	Pre-resolved widget config. Set this if you already have the config server-rendered or fetched app-wide — skips the bootstrap fetch.
onResize	(size: { width: number; height: number }) => void	Fired whenever the widget's intended dimensions change (open ↔ closed ↔ expanded). Use for host-side layout sync.
onOpen	() => void	Fired when the visitor opens the panel (taps the launcher, peek bubble, etc.).
onClose	() => void	Fired when the visitor taps the close chip.
className	string	Pass-through class on the outer host <div>. Style this with normal layout CSS.
style	React.CSSProperties	Pass-through inline styles for the outer host <div>.

UI locale is operator-controlled. The widget ships 33 UI locales (English, Ukrainian, German, Spanish — incl. es-MX, French, Italian, Dutch, Portuguese — incl. pt-BR, Swedish, Danish, Norwegian, Finnish, Polish, Czech, Slovak, Turkish, Romanian, Hungarian, Greek, Arabic, Hebrew, Hindi, Thai, Vietnamese, Indonesian, Japanese, Korean, Chinese — zh + zh-TW, plus regional English variants). The operator's localeStrategy (set in the Wexio dashboard) decides whether to follow the visitor's browser (AUTO), the host page's <html lang> (WEBSITE), or pin to a chosen language (DEFAULT + defaultLocale). The visitor can also override their language from the in-widget Profile tab.

Bot protection (Cloudflare Turnstile)

When the operator enables Cloudflare Turnstile for the integration (Wexio dashboard → Security), the widget transparently runs an interaction-only challenge before the visitor handshake — no host wiring required. The launcher stays unclickable until the challenge resolves; on failure a small "couldn't verify you're human" popup appears anchored above the launcher with a retry button. The challenge token is attached to the prechat and identified-visitor handshake server-side, so operator-side rate-limiting / abuse rules apply automatically.

Methods

The component's open / close lifecycle is driven via the onOpen / onClose callbacks plus the visitor's tap on the launcher — no host-side imperative call is needed for normal use.

An imperative window.WexioWidget surface (show, hide, showSpace, setLocale, onUnreadCountChange, …) is on the roadmap to mirror the script loader's API, but doesn't ship in the current React package. For deep-link / programmatic control today, mount the widget conditionally from your own host state.

Types

VisitorIdentity

interface VisitorIdentity {
  googleIdToken?: string; // Google FedCM id_token (preferred)
  jwt?: string;           // Host-signed JWT
  userId?: string;        // Legacy HMAC pair…
  userHash?: string;      // …(HMAC-SHA256(userId, integrationSecret))
  name?: string;
  email?: string;
  phone?: string;
  attributes?: Record<string, unknown>;
}

InjectableWidgetConfig

The pre-resolved widget config shape (theme, features, blocks, prechat, messenger chrome, sounds, locale strategy, bot protection). Pull it from the package:

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

The integration's Cloudflare Turnstile bot-protection check (when the operator enables it in the Wexio dashboard) is wired automatically — the widget loads the CF script, runs the challenge before the visitor handshake, and shows a retry popup above the launcher if the challenge fails. Hosts don't need to wire anything extra.

SSR

The component renders null on the server. The Shadow-DOM portal target mounts on the first useEffect, so the widget is invisible during SSR/hydration and appears on first paint. Wrap in <Suspense fallback={null}> if you need to defer hydration in RSC-heavy apps.

Browser support

Modern evergreen browsers — anything that supports Shadow DOM and ES2020. Internet Explorer is not supported.

Troubleshooting

Messenger not showing on page

• Check that the correct publicKey is being passed.
• Check the messenger is active for your integration on https://app.wexio.io.
• Confirm the component renders on the client (not during SSR) — <WexioWidget> returns null until the first useEffect.

No user data attached

• Verify you're computing userHash server-side as HMAC-SHA256(userId, integrationSecret). Never expose the integration secret to the browser.
• Confirm the proof you pass in user is one of: googleIdToken, jwt, or userId + userHash. Passing multiple proofs uses the first one detected (Google → jwt → HMAC).

TypeScript errors after upgrade

The public type surface is locked to entries/public.ts in the source repo. If you previously relied on undocumented props (locale, prefill, lightboxViewport, mode, configOverride, useDummyData, previewData), they are no longer exposed — they were either dashboard-only or moved to operator-side config. Remove them and the build will pass. The widget auto-resolves to production when publicKey is set and demo (bundled mock content) otherwise; UI locale is controlled by the operator's localeStrategy config and the visitor's Profile-tab language switcher.

Use with other frameworks

The underlying widget runtime is a Web Component, so it works in any modern framework — even without a typed wrapper:

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

Typed wrappers for the popular frameworks:

• @wexio/messenger-widget-vue — Vue 3
• @wexio/messenger-widget-angular — Angular
• @wexio/messenger-widget-ember — Ember

For plain HTML / script-injection setups, paste the loader snippet from https://learn.wexio.io/docs/web-widget.

Author

👤 Wexio (https://wexio.io)

Show your support

Give a ⭐️ if this package helped you!

Changelog

See the Releases page for the full changelog.

📝 License

This project is MIT licensed.

---

Created with ❤️ by Wexio