Widget Integration

What the widget looks like

The widget mid-call, with most of the optional chrome switched on:

• Top-left button row — fullscreen, captions (highlighted while the transcript is showing), text input, and the opt-in inputMode dropdown, currently set to "Voice".
• Avatar stage — the lipsync video, framed by videoFit and videoPosition.
• Transcript panel — the scrolling user/AI exchange overlaid across the bottom of the stage.
• Bottom control row — mic mute, and the call button in its red connected state.

Driving it from elsewhere on the page

Without holding a reference to the bubble:

// Drive the bubble from anywhere on the page, no reference needed
window.dispatchEvent(new CustomEvent('konai:bubble:open'));
window.dispatchEvent(new CustomEvent('konai:bubble:close'));

Escape also closes it. Under 480px wide the panel goes near-fullscreen.

Panorama requirements

The panorama image must be:

• HTTPS (enforced by the widget)
• Equirectangular (2:1 aspect ratio)
• CORS-enabled on its origin (required for the WebGL texture load)

Panoramas are sticky by design — the guest explores until the server dismisses the tour, with a 10-minute hard cap as a safety net. There is no auto-dismiss when the avatar stops speaking.

Virtual tour prerequisite

Google Map events

Kiosk flow

The menu appears → the guest taps a button → the widget sends { type: 'kiosk:set_domain', domain } → the server scopes the avatar's prompt and tools to that domain and greets in-domain. When the guest wraps up, the avatar calls kiosk_return_to_menu, the server pushes { type: 'kiosk:return_to_menu' }, and the widget clears the domain and re-shows the buttons. The same call stays alive throughout.

Bottom control row

Top button row

Status, transcript, and header

• Status indicator (showStatus): a live status pill — Live / Listening / Speaking / Processing / Muted.
• Transcript panel (showTranscript): a scrolling caption panel showing user and AI text. Auto-hides during display tools that would overlap it.
• Header (showHeader): the top bar with the avatar's name and "Online" subtitle.

Voice — default

Always-listening mode. The guest speaks whenever they want; speech is detected and committed automatically, and speaking over the avatar interrupts it. No button hold required. Best for normal conversational interfaces and quiet-environment demos.

Push-to-Talk

Set pushToTalk: true, or enable runtime switching via uiDetails.showTopButtons.inputMode: true. The mic starts muted and the guest holds a walkie-talkie button to talk, so the button's release is the utterance boundary. Best for exhibitions, kiosks, and noisy environments where always-listening produces false positives.

Barge-in / interruption control

allowInterruption: true (default) lets the guest interrupt the avatar mid-response by speaking or via the interrupt button. Setting it to false enforces strict turn-taking:

• Voice barge-in blocked
• Interrupt button hidden
• sendTextMessage() refuses and returns false while the avatar is speaking
• interruptAI() becomes a no-op

Best for scripted demos, interviews, and compliance flows where the avatar must finish each turn.

Minimalist mode

No chrome at all — just the avatar and the call button.

// Minimalist — just the avatar and a call button
init({
    sessionEndpoint: '/api/widget-session',
    uiDetails: {
        showHeader: false,
        showStatus: false,
        showTranscript: false,
        showTopButtons: false,
        showControls: { call: true, mute: false },
    },
});

Exhibition kiosk

Portrait, push-to-talk, strict turn-taking, no chrome.

// Exhibition kiosk — portrait, push-to-talk, strict turn-taking
init({
    sessionEndpoint: '/api/widget-session',
    pushToTalk: true,
    allowInterruption: false,   // the avatar finishes every turn
    videoFit: 'cover',          // full-bleed portrait
    videoPosition: 'top',
    uiDetails: {
        showHeader: false,
        showStatus: false,
        showTopButtons: { fullscreen: true, captions: false, textInput: false },
    },
});

Full-featured customer support widget

Every control enabled, themed to your brand, with analytics hooks.

// Full-featured support widget — every control, analytics wired up
init({
    sessionEndpoint: '/api/widget-session',
    theme: { primaryColor: '#0ea5e9', secondaryColor: '#6366f1' },
    uiDetails: {
        showControls: { call: true, mute: true, interrupt: true, audioMute: true },
        showTopButtons: { fullscreen: true, captions: true, textInput: true, inputMode: true },
    },
    onTranscription: (text) => analytics.track('user_said', { text }),
    onResponse:      (text) => analytics.track('avatar_said', { text }),
});

What differs from vanilla

Three config keys are managed by the components — passing them has no effect:

• containerId — <KonproWidget> creates and owns its mount node.
• bubble — use the bubble prop on <KonproBubble> instead.
• The callbacks — pass them as props, not inside config, so they stay late-bound.

Everything else in config behaves exactly as it does in the vanilla package.

Controlling the widget

Grab the instance from onReady and call any instance method:

function Assistant() {
  const widget = useRef(null);

  return (
    <>
      <KonproWidget
        config={{ sessionEndpoint: '/api/widget-session' }}
        onReady={(w) => { widget.current = w; }}
      />
      <button onClick={() => widget.current?.toggleCall()}>Call</button>
      <button onClick={() => widget.current?.toggleMute()}>Mute</button>
    </>
  );
}

Behaviour worth knowing

• Config applies once, on mount. The widget has no updateConfig(), and re-applying config mid-call would tear down a live conversation. To change config, change the component's key and let React remount it.
• Callbacks are late-bound. Pass inline arrows freely — they are forwarded through a ref, so they neither re-initialise the widget nor go stale.
• StrictMode-safe. React 18's mount/unmount/remount cycle is handled: the widget guards its async initialisation against a teardown landing mid-flight, so no orphaned session or duplicate DOM is left behind.

Next.js / SSR

Both components are marked 'use client', and @konpro/widget sets no globals and touches no DOM at import time, so importing it during SSR is safe.

'use client';
import { KonproBubble } from '@konpro/widget-react';

export default function Assistant() {
  return <KonproBubble config={{ sessionEndpoint: '/api/widget-session' }} />;
}

TypeScript

Types ship with the package and are re-exported from @konpro/widget:

import type {
  KonproWidgetConfig,
  KonproWidgetInstance,
  KonproBubbleOptions,
  AvatarState,
} from '@konpro/widget-react';

Baseline

script-src   'self' https://cdn.konpro.ai;
style-src    'self' 'unsafe-inline';
connect-src  'self' wss://api.konpro.ai https://api.konpro.ai https://inference.konpro.ai;
img-src      'self' data: https:;
media-src    'self' blob:;

• cdn.konpro.ai — the widget bundle.
• wss://api.konpro.ai — the session WebSocket.
• https://api.konpro.ai — session REST calls.
• https://inference.konpro.ai — MediaSoup HTTP endpoints (session/connect, transport/connect, consumer/resume).
• style-src 'unsafe-inline' — the widget injects its stylesheet as a <style> block.
• media-src blob: — <video srcObject> MediaStream binding.
• img-src https: — avatar images and any display content.

Feature-gated additions

Add only what your avatar actually uses:

# Panorama (mediaType: 'panorama')
script-src   ... https://cdn.jsdelivr.net;
connect-src  ... https://cdn.jsdelivr.net https://<panorama-image-hosts>;
img-src      ... https://<panorama-image-hosts>;

# Virtual tour (mediaType: 'tour')
frame-src    https://studio.konpro.ai;

# Google Map (mediaType: 'city')
script-src   ... https://maps.googleapis.com https://maps.gstatic.com;
connect-src  ... https://*.googleapis.com https://*.google.com https://*.gstatic.com;
img-src      ... https://maps.googleapis.com https://maps.gstatic.com https://*.googleusercontent.com;
style-src    ... https://fonts.googleapis.com;
font-src     ... https://fonts.gstatic.com;

The AudioWorklet

Microphone capture runs in an AudioWorklet, and where that file is served from depends on how you installed the widget:

• CDN build — loads it as a sibling of the bundle, so allowing cdn.konpro.ai already covers it.
• npm install — depends on your bundler. Vite inlines it as a data: URI (it is under the 4KB limit); webpack and Rollup usually emit a real asset served from 'self'. If either is blocked, the widget falls back to a blob: worklet.
• If your CSP allows none of those — host @konpro/widget/dist/mic-capture.worklet.js yourself and point workletUrl at it.

Permissions Policy (microphone)

Permissions-Policy: microphone=(self), autoplay=(self), fullscreen=(self)

In an iframe you also need allow="microphone; autoplay; fullscreen" — both the parent header and the iframe attribute must grant it, and the intersection wins. To verify, open DevTools → Application → Permissions Policy, or check document.featurePolicy?.allowsFeature('microphone') in the console.

iframe embeds

If you embed the widget inside an <iframe> rather than including it directly, the iframe needs:

<iframe
  src="..."
  allow="microphone; autoplay; fullscreen"
  allowfullscreen
></iframe>

Without allow="microphone", getUserMedia will silently reject.