Installation

Install

npm install @monoverse/voicebot-react

react and react-dom are peer dependencies (17, 18, or 19).

Render the widget

Render <VoiceBotWidget> once, near the root of your app. It renders nothing visible itself — the widget UI is mounted by the deployed bundle it loads.

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

export function App() {
  return (
    <>
      <YourApp />
      <VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
    </>
  );
}

The component is a singleton: rendering it more than once (or re-rendering across SPA route changes and React StrictMode) never injects a second script or opens a second WebSocket/microphone.

Voice or chat

<VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" variant="voice" /> {/* default → widget-voice.js */}
<VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" variant="chat" />  {/* → widget-chat.js */}

Props

Prop	Type	Default	Description
publicKey	string (required)	—	Your pk_ publishable key.
variant	'voice' | 'chat'	'voice'	Which widget bundle to load.
lang	string	—	Force the widget UI language (e.g. 'uk', 'en'). Omit to let the backend pick.
scriptSrc	string	https://api.monoverse.tech/widget	Override the CDN base (self-hosted API).
onError	(error: Error) => void	—	Called on script load failure or an empty key.
onNavigate	(target: VoiceBotNavTarget) => void	—	Called on any bot navigation. Route it through your SPA router so the live session survives.
onAction	VoiceBotActionHandlers	—	Cart / variant / filter handlers — the acting tier. See Capabilities & host actions.
capabilities	VoiceBotCapability[]	—	Narrow the server-granted capability set for the current page (narrow-only; never widens it).
toolHandlers	VoiceBotToolHandlers	—	Low-level override for canonical action names. Most apps use onAction instead.

The last three (onAction, capabilities, toolHandlers) and onNavigate are the acting tier — they let the bot add to cart, pick a variant, filter, and navigate. See Capabilities & host actions and Custom site integration.

Hook (imperative)

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

function WidgetMount() {
  useVoiceBot({ publicKey: 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', variant: 'chat' });
  return null;
}

Next.js

The component is SSR-safe — it injects the script in an effect and renders null on the server, so it works in both the App Router and the Pages Router. In the App Router, mark the host as a client boundary and render once in the root layout:

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

export function VoiceBot() {
  return <VoiceBotWidget publicKey="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />;
}

You can also use Next's own next/script directly without this package — this package exists so you do not have to.

The package source, props table, and changelog live in the package README on npm.