Skip to main content
Version: v1

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 works now vs. the next tier​

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

Next tier (not in the embed) — first-party actions: routing add_to_cart, navigation, or other writes into your own app state. That needs the handler-registration SDK (createWidget + merchant executors) and is a separate path. The script tag is an injector, not an action bridge.

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.