SDK reference

The SDK reference is a reference document covering the widget's initialization options, runtime API and events. The widget works with just the two lines of installation code, so this document is for when you need to change the language, turn off a specific feature, or receive widget state in your site code.

All options are optional. If you do not specify them, the widget uses the defaults in the tables below.

Script address

Address	Nature	When to use
`https://addon-cdn.voidx.ai/latest/voidx-ai-addon.standalone.js`	Updated with every release	Demos, testing
`https://addon-cdn.voidx.ai/v{version}/voidx-ai-addon.standalone.js`	Never changes once published	Production sites

Loading the script creates window.VoidxAIAddon, and calling init(config) draws the widget. The widget does not affect the host site's styles and is not affected by them.

Initialization options

JavaScript
const voidx = window.VoidxAIAddon.init({
  apiKey: 'YOUR_API_KEY',
  locale: 'en',
  features: { voice: false, productPress: true },
  contact: 'help@example.com',
});

Option	Type	Default	Description
`apiKey`	`string`	None (required)	Widget key. Without it, `init()` throws an error and draws nothing
`locale`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`'ko'`	Language of widget copy and answers. It does not read the visitor's browser language automatically, so on multilingual sites set it to match the page language
`features`	object	See table below	Turns individual features on or off
`theme`	object	See table below	Colors, font and corners
`hoverTargets`	object	See table below	Rules for elements targeted by hover detection
`productPress`	object	See table below	Picking a product by long-press or long hover
`contact`	`string`	None	Contact shown to visitors when the token limit is used up. If empty, the message reads "Please contact the site operator"
`telemetry`	`false \| object`	Enabled	Set to `false` to turn off the widget's own telemetry
`onReady`	`() => void`	None	Callback when the widget is ready
`onError`	`(error: Error) => void`	None	Error callback
`onMessage`	`(message) => void`	None	Callback when a message is received

`features`

Key	Default	Description
`chat`	`true`	Chat window and speech bubble above the character
`cursor`	`true`	Character floating on the screen
`voice`	`false`	Voice chat. `true` is a request, and it turns on only when the plan allows it. Provided under Customize contracts
`hoverDetection`	`true`	Cursor-reaction trigger and hover detection event
`productPress`	`false`	Hands a product off to chat when it is long-pressed or hovered for a long time
`agentMode`	`'3d'`	Character rendering mode

With voice: false, voice is off regardless of plan. If you turned it on and the voice button does not appear, check the contract, not the code.

`theme`

Key	Default
`primaryColor`	`#587efa`
`gradientFrom`	`#3762f2`
`gradientTo`	`#31a9ff`
`fontFamily`	`Pretendard, -apple-system, BlinkMacSystemFont, sans-serif`
`borderRadius`	`20` (px)

`hoverTargets`

Determines whether to fire the voidx:hover:detected event when the cursor stays over an element for 1.5 seconds. Matching is checked in this order: ids exact match, classNames exact match, idPatterns, classNamePatterns.

Key	Default
`classNames`	`['product-item', 'voidx-target']`
`ids`	`[]`
`idPatterns`	`[/^product-[A-Za-z0-9]+$/, /product-\w+/]`
`classNamePatterns`	`[/^voidx-/]`

`productPress`

Detailed behavior when features.productPress is on.

Key	Default	Description
`pressMs`	`550`	Time (ms) to count as a long-press on touch and pen
`hoverMs`	`900`	Time (ms) to count as a long hover with a mouse
`hoverEnabled`	`true`	Whether mouse long hover is used
`cooldownMs`	`6000`	Interval (ms) before the same product can be picked again
`mode`	`'greet'`	`greet` shows an "Interested in {product name}?" bubble, `send` sends the product name as a visitor message, `prefill` opens the chat window and only fills the input with the product name
`suppressNativeMenu`	`true`	Blocks the browser's default menu and text selection on long-press
`urlPattern`	None	Regular expression for detecting product detail addresses. When set, it is used instead of the default token list. An invalid pattern is ignored and the default list is used

Runtime API

Control the widget with the instance that init() returns.

JavaScript
const voidx = window.VoidxAIAddon.init({ apiKey: 'YOUR_API_KEY' });

voidx.show();
voidx.on('voidx:chat:open', () => console.log('opened'));

Method	Description
`show()`	Opens the chat window
`hide()`	Closes the chat window
`sendMessage(text)`	Sends a message as if the visitor had typed it
`announceSystemEvent(context, { instruction?, openChat? })`	Shows only an agent answer, without a visitor bubble. Used to announce site events such as a completed order. Skipped if the conversation has not started yet
`setTheme(partial)`	Changes part of the theme
`setLocale(locale)`	Changes the language
`on(event, handler)` / `off(event, handler)`	Subscribe to and unsubscribe from events
`destroy()`	Removes the widget and cleans up the DOM and state

Events

Receive events with on(), or as a window CustomEvent with the same name.

Event	Data	When
`voidx:ready`	None	Widget is ready
`voidx:error`	`Error`	An error occurred
`voidx:message`	Message object	A message was received
`voidx:auth:expired`	`{ status }`	Visitor authentication expired. The widget renews it on its own, so no action is needed
`voidx:chat:open`	None	Chat window opened
`voidx:chat:close`	None	Chat window closed
`voidx:voice:start`	None	Voice chat started
`voidx:voice:end`	None	Voice chat ended
`voidx:voice:error`	`{ message }`	Voice error
`voidx:hover:detected`	`{ element }`	Cursor stayed over a hover detection target for 1.5 seconds
`voidx:product:captured`	`{ product, element }`	A product was picked by long-press or long hover
`voidx:action:executed`	`{ name, params, result }`	A host action ran
`voidx:action:error`	`{ name, params, error }`	A host action failed
`voidx:destroy`	None	Widget cleaned up

React wrapper `@voidx-ai/react`

Bash

npm install @voidx-ai/react

The VoidxAddon component loads the script, calls init() for you, and also handles destroy() when it unmounts. It requires React 18 or later.

Prop	Description
`apiKey`	Widget key (required)
`features`	Feature settings
`theme`	Theme
`locale`	Language. When the value changes, `setLocale` is called automatically
`scriptUrl`	Script address. To pin the version on a production site, set a `/v{version}/` address
`hoverTargets`	Hover detection target rules
`onReady` / `onError` / `onMessage`	Callbacks
`disabled`	When `true`, the script is not loaded
`children`	Children access the instance with the `useVoidx()` hook

TSX
import { VoidxAddon, useVoidx } from '@voidx-ai/react';

function OpenChatButton() {
  const voidx = useVoidx();
  return <button onClick={() => voidx?.show()}>Chat with us</button>;
}

The wrapper's features type has no productPress key. To turn this feature on in TypeScript, pass the object with a type assertion.

TSX
import type { VoidxFeatures } from '@voidx-ai/react';

const features = { chat: true, productPress: true } as VoidxFeatures;
<VoidxAddon apiKey={key} features={features} />;

The widget is reinitialized only when apiKey or disabled changes. Callbacks use the values from the initial initialization.

Next steps

For installation steps and version pinning, see Widget installation.
For product detection rules, see Preparing your site.
For changing features and language from the console, see Widget settings.

Script address#

Initialization options#

features#

theme#

hoverTargets#

productPress#

Runtime API#

Events#

React wrapper @voidx-ai/react#

Next steps#

Next steps

Script address

Initialization options

`features`

`theme`

`hoverTargets`

`productPress`

Runtime API

Events

React wrapper `@voidx-ai/react`

Next steps