Skip to main content
Version: next

Next.js (Browser Widget)

@monoverse/voicebot-next is an npm package that drops the VoiceBot talking widget onto a Next.js app with one component and your public key, loaded the Next way via next/script.

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-next';

<VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />;

Why a Next-specific wrapper​

The React wrapper also works in Next.js (inside a client boundary). This package exists to load the bundle via next/script with strategy="afterInteractive", which is the idiomatic App Router path: Next dedupes the <script> tag and sequences loading after hydration. The component is 'use client', but importing it into a Server Component layout is fine.

Prefer a generic useEffect injector that fully removes the tag on cleanup? Use @monoverse/voicebot-react — see the teardown note on the installation page.

Embed vs. the Next wrapper​

The deployed bundle is plain JS, so a single <script ... data-public-key> tag works with no package at all (see the Vanilla path). The Next wrapper is the right choice when you want next/script semantics — hydration-aware loading and tag dedup — without writing the <Script> boilerplate yourself.

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 Node 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 Next.js app state. Wire them via the onAction prop (plus capabilities and toolHandlers) inside a Client Component. The wrapper passes these through to window.VoiceBotSyncBridge for you. See Capabilities & host actions for the full guide.

Next steps​

  • Installation — install, render in the root layout, and the teardown caveat.
  • Provisioning — get a pk_ and register your origins.
  • Runnable example app — a complete clone → run Next.js App Router app that mounts <VoiceBotWidget> in the root layout.