Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vizochok.com/llms.txt

Use this file to discover all available pages before exploring further.

The VIZOCHOK widget is a lightweight JavaScript SDK (@vizochok/widget) that embeds an AI-powered shopping assistant into any web page. It uses Shadow DOM for style isolation and communicates with the VIZOCHOK backend over WebSocket for real-time streaming.

​
Prerequisites

  • A VIZOCHOK tenant with a public API key (pk_...)
  • Your store ID (configured in the admin panel)
Never use your secret key (sk_...) in frontend code. The widget requires a public key with chat scope only.

​
Quick Start

1

Install the SDK

Install via npm or load from CDN. See Installation for all options.
npm install @vizochok/widget
2

Create and mount the widget

import { VizochokWidget } from '@vizochok/widget';

const widget = new VizochokWidget({
  apiKey: 'pk_your_public_key',
  storeId: 'your-store-id',
  userId: 'customer-123',
  language: 'uk',
});

widget.mount();
This appends the widget to document.body. A floating chat button appears in the bottom-right corner.
For all configuration options, see Configuration Reference. For theming and visual customization, see Theming. For event callbacks and cart synchronization, see Events & Callbacks. For framework-specific examples (React, Vue, Svelte, Astro), see Examples.

​
Inline Mode

By default, the widget renders as a floating button that opens a chat panel. You can embed it inline within a specific container instead: 
const container = document.getElementById('chat-container');
widget.mount(container, { inline: true });
In inline mode:
  • The widget fills 100% width and height of the container
  • The floating toggle button is hidden
  • The chat panel is always open
  • You control visibility via the container’s CSS
<div id="chat-container" style="width: 400px; height: 600px;"></div>

<script>
  const widget = new VizochokWidget({
    apiKey: 'pk_your_public_key',
    storeId: 'your-store-id',
  });
  widget.mount(document.getElementById('chat-container'), { inline: true });
</script>

​
Switching Modes at Runtime

You can switch between inline and floating mode without losing the conversation: 
// Switch to inline mode
widget.setMode('inline', document.getElementById('chat-panel'));

// Switch back to floating mode
widget.setMode('floating');

​
Programmatic Control

The widget instance exposes methods for programmatic control: 
widget.open();      // Open the chat panel
widget.close();     // Close the chat panel
widget.toggle();    // Toggle open/closed
widget.newChat();   // Clear history and start a new conversation
widget.unmount();   // Remove widget from DOM, preserve session in sessionStorage
widget.destroy();   // Remove widget and clear all session data

​
Dynamic Store Switching

If the user changes their delivery address and the nearest store changes, update the widget without re-creating it: 
// User selected a new delivery address → your backend resolved a different store
widget.setStoreId('store-kyiv-143');
This clears the current conversation (product availability differs between stores) and reconnects with the new store context. See Configuration — Store ID for details.

​
Shadow DOM & Style Isolation

The widget renders inside a Shadow DOM, which means:
  • Your page styles do not affect the widget
  • The widget styles do not leak into your page
  • CSS custom properties are used for theming (set via the theme config)
Because the widget uses Shadow DOM, external CSS frameworks (Bootstrap, Tailwind) will not style the widget’s internals. Use the theme configuration object instead.

​
Content Security Policy (CSP)

If your site uses a strict Content Security Policy, add these directives: 
connect-src https://api.vizochok.com wss://api.vizochok.com;
script-src https://cdn.jsdelivr.net;
style-src 'unsafe-inline';
The style-src 'unsafe-inline' is needed because the widget injects styles into its Shadow DOM. If your CSP does not allow inline styles, the widget’s UI will not render correctly.

​
Performance Notes

  • Bundle size: The SDK is ~12 KB gzipped with zero external dependencies.
  • Lazy connection: The WebSocket connection is established on mount(), not on instantiation.
  • Session persistence: Conversation state is saved to sessionStorage so the user can refresh the page without losing context.
  • Heartbeat: The widget maintains a heartbeat ping every 30 seconds. If no response is received within 60 seconds, the connection is automatically closed and reconnected.