> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voltai.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Examples
> Common patterns and use cases
Here are some common ways to use the Voltai Widget.
## Basic setup
The simplest integration—just load and go:
```html theme={null}
My Site
Welcome
```
## Custom branded theme
Match the widget to your brand colors:
```javascript theme={null}
const voltai = Voltai.load({
apiKey: 'your-api-key',
enableGuestUser: true,
title: 'Acme Support',
colors: {
// Primary brand color
bgButtonPrimary: '#FF6B00',
textPrimaryBrand: '#FF6B00',
iconPrimaryBrand: '#FF6B00',
// Text on primary buttons
textPrimaryInverse: '#FFFFFF',
iconInverse: '#FFFFFF'
}
});
```
## Help button integration
Open the widget from your own button instead of (or in addition to) the floating button:
```html theme={null}
```
## Contextual help
Send a pre-filled question based on where the user is on your site:
```html theme={null}
```
## Event tracking
Track widget usage for analytics:
```javascript theme={null}
const voltai = Voltai.load({
apiKey: 'your-api-key',
enableGuestUser: true,
onReady: () => {
console.log('Widget mounted');
},
onAuthReady: ({ isLoggedIn, isGuest }) => {
console.log('Auth initialized', { isLoggedIn, isGuest });
},
onOpen: () => {
// Track in your analytics
gtag('event', 'widget_open', {
event_category: 'Support'
});
},
onClose: () => {
gtag('event', 'widget_close', {
event_category: 'Support'
});
}
});
// Track messages
voltai.on('chat:send', (payload) => {
gtag('event', 'chat_message', {
event_category: 'Support',
event_label: payload.topics?.join(', ')
});
});
```
## Sync host auth before opening
Use `onAuthReady` when you want to make an auth decision before the widget is opened:
```javascript theme={null}
const voltai = Voltai.load({
apiKey: 'your-api-key',
enableGuestUser: true,
onAuthReady: async ({ isLoggedIn }) => {
if (!isLoggedIn) {
await voltai.login();
}
}
});
```
If the visitor later opens the widget without a session and guest access is enabled, the normal captcha and guest verification flow still happens inside the widget.
## Handle widget auth clicks yourself
Use `authClickEvents.mode` when you want the widget to emit auth click events but let your app decide what to do next.
* `observe` keeps the normal widget auth flow
* `intercept` stops the normal widget auth flow so your page can handle auth itself
```javascript theme={null}
const voltai = Voltai.load({
apiKey: 'your-api-key',
authClickEvents: {
mode: 'intercept'
}
});
voltai.on('auth:sign-in-click', () => {
openYourLoginModal();
});
voltai.on('auth:sign-out-click', () => {
signOutFromYourApp();
});
```
`voltai.login()` and `voltai.logout()` still work normally in `intercept` mode.
## Widget control buttons
Create a custom control panel:
```html theme={null}
```
## Form with topic selection
Let users choose a topic before starting a chat:
```html theme={null}
```
## React integration
Using the widget in a React application:
```jsx theme={null}
import { useEffect, useRef } from 'react';
function App() {
const voltaiRef = useRef(null);
useEffect(() => {
// Initialize on mount
voltaiRef.current = window.Voltai.load({
apiKey: 'your-api-key',
enableGuestUser: true,
onReady: () => console.log('Widget ready')
});
// Cleanup on unmount
return () => {
voltaiRef.current?.destroy();
};
}, []);
const openChat = () => {
voltaiRef.current?.open();
};
return (
My React App
);
}
```
Make sure the widget script is loaded before your React app mounts. You can add it to your `index.html` or load it dynamically.
## Multi-organization authenticated users
If your users can access more than one organization, set `defaultOrgName` so the widget prefers the org you expect:
```javascript theme={null}
const voltai = Voltai.load({
apiKey: 'your-api-key',
authConnection: 'EXAMPLE',
defaultOrgName: 'Acme',
title: 'Acme Support'
});
```
This is useful when a single user account belongs to multiple orgs and you want the widget to open in the same org context as the rest of your site.