JS API reference

Every method available from embed.js. This is the lookup table — for narrative usage, see Headless mode or Install.

Roxels global

Roxels.init(options)

One-time setup with config and callbacks. Sets defaults applied to subsequent open() / start() calls. Renders the persistent launcher button (if configured by the template).

Roxels.init({
  templateKey: "rk-...",
  personName: "Ada",
  externalId: "user_123",
  onComplete: (results) => {},
  onUnderstanding: (data) => {},
  onClose: () => {},
  onError: (err) => {},
  onGoalTransition: (event) => {},
  fabAnchor: "#header",
  fabContainer: document.body,
});

Roxels.start(options) ⭐

The main entry point. Mounts an iframe, returns a controller. Use this for every new integration.

const call = Roxels.start({
  templateKey: "rk-...", // or sessionId
  display: "modal" | "compact" | "none", // defaults to "modal"
  personName: "Ada",
  externalId: "user_123",
  context: {
    /* template-specific context */
  },
});

Returns: a controller.

Roxels.open(options)

Legacy entry point. Thin shim over start(). New code should use start().

Roxels.open({ mode: "modal" }); // equivalent to start({ display: "modal" })

Roxels.close()

Closes the currently visible widget (modal or compact). For headless, use call.hangUp() or call.close() on the controller.

Roxels.destroy()

Tears down everything — the widget, the launcher, any active calls. Use on unmount in SPAs.

Roxels.showFab(opts) / Roxels.hideFab()

Show or hide the floating action button. Useful when the template's launcher visibility rules need to be overridden from your code.

Roxels.setView(name)

Update the current view identifier. The persistent launcher uses this to decide whether to show, based on visibility.{include,exclude} rules in the template's launcher config.

router.afterEach((to) => Roxels.setView(to.path));

Roxels.setPerson({ name, externalId })

Update the participant identity after init. Use when the user signs in or switches accounts.

Roxels.loadLauncherConfig()

Fetch the latest launcher config from the backend. Normally called automatically by init.

Roxels.send(message)

Send an arbitrary message to the currently active call's agent. Same as call.send(...) but on the global. The message is relayed on the host-command data channel.

Global control proxies

These delegate to the currently active call's controller — useful when your UI is divorced from the controller object.

Roxels.pause();
Roxels.resume();
Roxels.togglePause();
Roxels.muteMic();
Roxels.unmuteMic();
Roxels.toggleMic();
Roxels.setMicEnabled(boolean);
Roxels.startScreenShare();
Roxels.stopScreenShare();
Roxels.toggleScreenShare();
Roxels.sendMessage(text);
Roxels.uploadFile(file);
Roxels.hangUp();
Roxels.on(event, callback);
Roxels.off(event, callback);

Properties

Controller

The object returned by Roxels.start(...). The shape is identical for modal, compact, and headless modes.

State

call.state; // live state snapshot (status, voice_state, mic_state, etc.)
call.sessionId; // string | null — set once the session id is known
call.ready; // Promise<void> — resolves on `connected`, rejects on early error

Subscriptions

call.on(event, callback);
call.off(event, callback);

See Events for the full event catalog.

Commands

call.pause();
call.resume();
call.togglePause();
call.muteMic();
call.unmuteMic();
call.setMicEnabled(boolean);
call.toggleMic();
call.startScreenShare();
call.stopScreenShare();
call.toggleScreenShare();
call.sendMessage(text);
call.uploadFile(file); // or { files: File[] }
call.hangUp(); // graceful end → emits `ending` → `ended` → `complete`
call.send({ type, payload }); // escape hatch for custom commands

Lifecycle

call.close(); // destroy: end call, remove iframe, stop mic, release room

Use close() on unmount in SPAs. Use hangUp() when you want the conversation to end gracefully (so the agent says goodbye, outputs fire, etc.).

Script-tag autoinit

The script can initialize itself from data-* attributes — no extra JS needed.

<script
  src="https://app.roxels.ai/embed.js"
  data-template-key="rk-..."
  data-person-name="Ada"
  data-external-id="user_123"
  data-view="checkout"
></script>

Equivalent to:

Roxels.init({
  templateKey: "rk-...",
  personName: "Ada",
  externalId: "user_123",
  view: "checkout",
});

TypeScript

A .d.ts file is shipped at https://app.roxels.ai/embed.d.ts. You can reference it in your project:

/// <reference types="https://app.roxels.ai/embed.d.ts" />

Or copy it into your project for offline type-checking.

Read next

• Events — Full event catalog with payload shapes.
• Headless mode — Narrative guide to using the controller.
• Display modes — Modal vs compact vs headless behavior.