Widget runtime API

Once the widget loads, it installs a window.syncanix object you can call from your own code.

What you can do

• open() / close() / toggle() — open, close or flip the chat panel from your own code.
• isOpen — whether the panel is open right now, so your own button can show the matching state.
• setPosition(position) — move the launcher to another corner.
• enable() / disable() — turn the chat on or off at runtime without unmounting it (for incidents, checkout, or support hours).
• unmount() — remove the widget from the page.
• registerComponent() / unregisterComponent() / getComponentCatalog() — register your own React components for the assistant to render, validated with a schema.
• exposeShadowRoot(host, root) — tell the widget about a part of your page built with web components, so the assistant can see and operate the controls inside it. Returns a function that undoes it.
• registerDataSource() / unregisterDataSource() / getDataSourceCatalog() — hand the assistant a named way to fetch data from your app, so a composed answer can show live numbers rather than describing them.
• registerAction() / unregisterAction() / getActionCatalog() — let the assistant call your own functions, optionally schema-validated and confirmation-gated.
• setContext() / clearContext() — feed live host-app state (user, page, cart) into the next turn. Bounded JSON only — never secrets.
• setTokenProvider(fn) — provide the end user’s token per turn (takes precedence over the data attribute).
• setStepUpProvider(fn) — provide the step-up re-authentication flow.
• setHeadersProvider(fn) — add request headers (such as Authorization or a CSRF token) to each tool call; takes precedence over the data attribute.
• setTheme(key) — switch the live theme by name without remounting the chat (for a host light/dark toggle).
• setConsent(signal) — tell the widget what the visitor has agreed to, so it can follow the choice your own consent banner already collected.
• mapSite() / stopSiteWalk() and teach() / stopTeach() — start and stop the two operator-run mapping sessions from your own page. Each needs a one-time token generated in the dashboard, and neither can start without it.

Example

// Open the chat programmatically
window.syncanix.open();

// Feed live host-app context into the next turn (bounded JSON, no secrets)
window.syncanix.setContext({ page: 'checkout', cartItems: 3 });

// Provide the signed-in user's token per turn (recommended for SSR apps)
window.syncanix.setTokenProvider(async () => await getAccessToken());

What the assistant can render — and what it can’t see

The renderable surface is explicit by design: the built-in primitives, the components you register with registerComponent, and embeds from origins your admin has allowlisted. The assistant can only drive what you have deliberately handed it.

What the widget reads from your page is a separate question. Discovery is on by default and reads the STRUCTURE of your pages — which forms exist, what their fields are called, where your links go — proposing each as a capability for you to review. It never reads what anybody typed, and everything it finds arrives switched off.

Loaded once

Installing the global is idempotent — if the script is included twice, the duplicate is ignored with a warning, so you never end up with two widgets.

Next steps