Skip to main content
Version: next

Vanilla JS (Browser Widget)

The VoiceBot talking widget drops onto any website with a single <script> tag and your public key. There is no package here — the deployed bundle is plain JS that self-bootstraps from a script tag.

<script
  src="https://api.monoverse.tech/widget/widget-voice.js"
  data-public-key="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  async
></script>

That one tag is the entire integration. The deployed widget exchanges your pk_ (plus the browser-set Origin) for an origin-locked session token, then mounts into its own Shadow DOM host, grounded in your store's catalog. No merchant backend is required.

Embed-only — there is no @monoverse/voicebot-vanilla package

The framework wrappers (React, Vue, Next.js) are thin injectors that write this exact script tag for you. With no framework, you write the tag directly — there is nothing to npm install.

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 embed 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 app state. Set window.VoiceBotSyncBridge before the widget script tag to wire them. See Capabilities & host actions for the full guide including the complete bridge type reference.

Next steps​

  • Installation — the script tag, voice vs. chat, and the window.VoiceBot API.
  • Provisioning — get a pk_ and register your origins.
  • Runnable example app — a complete clone → run static HTML page with the one-tag embed.