Customising widgets

These options work on the voice button and the avatar panel. Pass them to mountVoiceButton, mountAvatar or the React components.

#Set the theme and colours

Pass a theme and your brand colours:

1mountVoiceButton({
2  flowKey: "YOUR_FLOW_KEY",
3  theme: "auto",          // "light", "dark" or "auto"
4  colors: { primary: "#0f766e", onPrimary: "#fff", surface: "#111", text: "#eee", danger: "#e5484d" },
5  radius: "14px",
6  fontFamily: '"Figtree", -apple-system, "Segoe UI", sans-serif',
7});

You can also set colours from your own CSS with --voxio-primary, --voxio-surface, --voxio-text and --voxio-radius.

#Place the widget

placementPlacement

bottom-right (default), bottom-left, top-right, top-left, bottom-center, or inline to sit inside a container.

offset{ x?, y? }

The distance from the edges. Numbers are pixels.

zIndexnumber

The stacking order.

mobile{ placement?, offset? }

Overrides for screens narrower than 640px.

draggableboolean | { snap?, remember? }

Lets visitors move it. It snaps to an edge and remembers the spot.

#Control when it appears

consentboolean | string

Asks before opening the microphone. true uses the default notice; a string is your own.

showWhenShowWhen

Starts hidden and appears on a trigger, such as { afterSeconds: 10 }, { scrollDepth: 0.5 } or { urlMatch: "/pricing" }.

hiddenboolean

Starts hidden. Call open() to show it.

sessionVoxioSession

Shares one session between widgets, such as a button and an avatar on the same call.

#Change the language and text

Pick a built-in language, or override any text the widget shows:

1mountVoiceButton({ flowKey: "YOUR_FLOW_KEY", locale: "hi" });   // built in: "en", "hi"
2mountVoiceButton({ flowKey: "YOUR_FLOW_KEY", strings: { start: "Speak to sales" } });

#Style it from your page

Widgets render in a shadow root, so your page's CSS doesn't reach inside. Style their named parts with ::part():

1voxio-voice-button::part(button) { box-shadow: 0 8px 30px rgb(0 0 0 / 0.4); }
2voxio-voice-button::part(label)  { font-weight: 600; }
3voxio-avatar::part(panel)        { border: 1px solid #333; }

For anything else, pass CSS as customStyles. It's added inside the shadow root.

#Listen for DOM events

Every widget fires these events on its element:

For example, to count finished calls in your analytics:

1document.querySelector("voxio-voice-button")
2  .addEventListener("voxio-ended", (e) => analytics.track("voice_call", e.detail));

#Next steps

• Web actions: let the agent act on your page.
• Errors: handle each error code.