Skip to main content
Version: next

React (Browser Widget)

@monoverse/voicebot-react is an npm package that drops the VoiceBot talking widget onto a React or Next.js app with one component and your public key.

It is a thin wrapper over the already-deployed VoiceBot browser embed. The package injects the CDN bundle and hands it your pk_; the deployed widget self-bootstraps — it exchanges the pk_ (plus the browser-set Origin) for an origin-locked session token and mounts, grounded in your store's catalog. No merchant backend is required, and there is no widget code in this package.

import { VoiceBotWidget } from '@monoverse/voicebot-react';

<VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />;

Channels​

This is Channel 2 — the browser widget for your end users. It is distinct from Channel 1 (server-side catalog/content sync, e.g. the Laravel package) that feeds the data the assistant is grounded in.

Origin locking​

Your pk_ is bound to an allow-list of exact origins that may use it. Matching is exact, with no wildcards — the origin is the security boundary.

  • List every origin explicitly. https://shop.example, https://www.shop.example, and https://app.shop.example are three different origins.
  • www and subdomains are not inherited — register each one separately.
  • An origin is scheme://host[:port]. http ≠ https, and a non-default dev port is part of the origin, so register your local origins too (e.g. http://localhost:5173).
  • Origin: null is never accepted — sandboxed iframes, file://, and other opaque origins cannot mint a token.
Two gates, same origin

The origin is checked twice: once when minting the session token (HTTP 403 on miss) and again on the WebSocket upgrade (close code 4403 on miss). Both must see an allow-listed origin.

What the wrapper supports​

Always available — a consultant grounded in your catalog: it answers product questions, recommends items, and describes your shipping and payment options from your store data.

Host actions (opt-in) — first-party actions like add to cart, variant selection, filtering, and navigation into your React app state. Wire them via the onAction prop (plus capabilities and toolHandlers). The wrapper passes these through to window.VoiceBotSyncBridge for you. See Capabilities & host actions for the full guide.

Next steps​