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.
The widget emits events that let you respond to user interactions and chat activity in your application.
Configuration callbacks
The simplest way to handle events is through callback functions in your configuration:
const voltai = Voltai.load({
apiKey: 'your-api-key',
onReady: () => {
console.log('Widget mounted');
},
onAuthReady: ({ isLoggedIn, isGuest }) => {
console.log('Auth initialized', { isLoggedIn, isGuest });
},
onOpen: () => {
console.log('Widget opened');
},
onClose: () => {
console.log('Widget closed');
},
onChatSend: (payload) => {
console.log('User sent:', payload.message);
},
onChatComplete: (payload) => {
console.log('Response:', payload.chatOutput);
},
onFeedbackSubmit: (payload) => {
console.log('Feedback submitted:', payload);
}
});
| Callback | Description |
|---|
onReady | Called when the widget shell has mounted |
onAuthReady | Called when auth initialization has completed. Receives { isLoggedIn, isGuest } |
onOpen | Called when the chat panel opens |
onClose | Called when the chat panel closes |
onChatSend | Called when a user sends a chat message. Receives { message, chatId, chatLink, userEmail } |
onChatComplete | Called when a chat response completes. Receives { chatId, chatOutput, chatLink, userEmail, success } |
onFeedbackSubmit | Called when a user submits feedback on a response. Receives { chatLink, chatId, feedbackContent, feedbackRating, feedbackType } |
Event listener API
For more control, use the on() and off() methods to subscribe to events dynamically.
on(event, handler)
Subscribe to an event.
const unsubscribe = voltai.on('widget:open', () => {
console.log('Chat opened');
});
off(event, handler?)
Remove event listeners.
// Remove a specific handler
voltai.off('widget:open', myHandler);
// Remove all handlers for an event
voltai.off('widget:open');
Available events
| Event | Payload | Description |
|---|
widget:ready | — | Widget shell mounted |
widget:open | — | Chat panel opened |
widget:close | — | Chat panel closed |
Chat events
| Event | Payload | Description |
|---|
chat:send | { message, chatId, chatLink, userEmail } | Message sent by user |
chat:complete | { chatId, chatOutput, chatLink, userEmail, success } | Chat response completed |
Feedback events
| Event | Payload | Description |
|---|
feedback:submit | { chatLink, chatId, feedbackContent, feedbackRating, feedbackType } | User submitted feedback on a response |
Authentication events
| Event | Payload | Description |
|---|
auth:ready | { isLoggedIn, isGuest } | Auth initialization completed |
auth:login | { isGuest } | User logged in |
auth:logout | — | User logged out |
auth:sign-in-click | { source, mode } | User clicked a widget sign-in button |
auth:sign-out-click | { source, mode } | User clicked a widget sign-out button |
auth:error | { error } | Authentication error occurred |
Event payloads
chat:send
Fired when a message is sent.
voltai.on('chat:send', (payload) => {
console.log('Message:', payload.message);
console.log('Chat ID:', payload.chatId);
console.log('Chat Link:', payload.chatLink);
console.log('User Email:', payload.userEmail);
});
| Property | Type | Description |
|---|
message | string | The message text |
chatId | string | Unique identifier for the conversation |
chatLink | string | URL to the chat conversation |
userEmail | string | Email of the user who sent the message. Empty string for guest users. |
chat:complete
Fired when a response has finished.
voltai.on('chat:complete', (payload) => {
console.log('Chat ID:', payload.chatId);
console.log('Response:', payload.chatOutput);
console.log('Chat Link:', payload.chatLink);
console.log('User Email:', payload.userEmail);
console.log('Success:', payload.success);
});
| Property | Type | Description |
|---|
chatId | string | The conversation identifier |
chatOutput | string | The chat response output (cleaned markdown) |
chatLink | string | URL to the chat conversation |
userEmail | string | Email of the user who received the response. Empty string for guest users. |
success | boolean | Whether the response completed successfully |
auth:ready
Fired when the widget has finished restoring or resolving the current auth state.
voltai.on('auth:ready', (payload) => {
console.log('Auth initialized:', payload);
console.log('Can safely read auth state now:', voltai.isAuthReady());
});
| Property | Type | Description |
|---|
isLoggedIn | boolean | true when the visitor is signed in with a non-guest account |
isGuest | boolean | true when the restored session is a guest session |
auth:login
Fired when a user logs in.
voltai.on('auth:login', (payload) => {
if (payload.isGuest) {
console.log('Guest user logged in');
} else {
console.log('User signed in');
}
});
| Property | Type | Description |
|---|
isGuest | boolean | true for guest users, false for signed-in users |
auth:logout
Fired when a user logs out.
voltai.on('auth:logout', () => {
console.log('User logged out');
});
auth:sign-in-click
Fired when a user clicks a sign-in button inside the widget.
Use authClickEvents.mode to choose what happens next:
observe keeps the normal widget auth flowintercept stops the normal widget auth flow so your page can handle auth itself
const voltai = Voltai.load({
apiKey: 'your-api-key',
authClickEvents: {
mode: 'observe'
}
});
voltai.on('auth:sign-in-click', (payload) => {
console.log('Sign-in clicked:', payload.source);
console.log('Mode:', payload.mode);
});
| Property | Type | Description |
|---|
source | "header" | "sign-in-prompt" | "guest-limit-dialog" | Which widget sign-in UI was clicked |
mode | "observe" | "intercept" | Whether the widget continues its built-in auth flow after the event |
intercept, widget button clicks stop at the event, but voltai.login() and voltai.logout() still work normally.
auth:sign-out-click
Fired when a user clicks the sign-out button inside the widget.
voltai.on('auth:sign-out-click', (payload) => {
console.log('Sign-out clicked:', payload.source);
console.log('Mode:', payload.mode);
});
| Property | Type | Description |
|---|
source | "header" | The current sign-out button location inside the widget |
mode | "observe" | "intercept" | Whether the widget continues its built-in auth flow after the event |
auth:error
Fired when an authentication error occurs.
voltai.on('auth:error', (payload) => {
console.error('Auth error:', payload.error);
});
| Property | Type | Description |
|---|
error | string | Description of the error |
feedback:submit
Fired when a user submits feedback on a response.
voltai.on('feedback:submit', (payload) => {
console.log('Chat:', payload.chatId);
console.log('Rating:', payload.feedbackRating);
console.log('Type:', payload.feedbackType);
console.log('Content:', payload.feedbackContent);
});
| Property | Type | Description |
|---|
chatLink | string | URL of the page where feedback was submitted |
chatId | string | Unique identifier for the conversation |
feedbackContent | string | The feedback text (comment or edited answer) |
feedbackRating | "up" | "down" | "neutral" | null | Thumbs up, thumbs down, neutral, or no rating |
feedbackType | "simple" | "advanced" | Whether the user used simple or advanced feedback |
Example: Analytics integration
Track widget usage with your analytics provider:
const voltai = Voltai.load({
apiKey: 'your-api-key',
onOpen: () => {
analytics.track('Widget Opened');
},
onClose: () => {
analytics.track('Widget Closed');
}
});
voltai.on('chat:send', (payload) => {
analytics.track('Chat Message Sent', {
chatId: payload.chatId,
userEmail: payload.userEmail
});
});
voltai.on('chat:complete', (payload) => {
analytics.track('Chat Response Received', {
chatId: payload.chatId,
chatLink: payload.chatLink,
success: payload.success
});
});
Example: Chat activity logging
Log user messages and AI responses using the callback API:
const voltai = Voltai.load({
apiKey: 'your-api-key',
onChatSend: (payload) => {
console.log('User email:', payload.userEmail);
console.log('Message:', payload.message);
console.log('Chat ID:', payload.chatId);
console.log('Chat link:', payload.chatLink);
},
onChatComplete: (payload) => {
console.log('Chat ID:', payload.chatId);
console.log('Chat output:', payload.chatOutput);
console.log('Chat link:', payload.chatLink);
console.log('User email:', payload.userEmail);
console.log('Success:', payload.success);
}
});
Example: Feedback tracking
Track user feedback using the callback API:
const voltai = Voltai.load({
apiKey: 'your-api-key',
onFeedbackSubmit: (payload) => {
console.log('Chat ID:', payload.chatId);
console.log('Chat link:', payload.chatLink);
console.log('Rating:', payload.feedbackRating);
console.log('Type:', payload.feedbackType);
console.log('Content:', payload.feedbackContent);
}
});
Example: Cleanup on unmount
In a single-page app, clean up listeners when navigating away:
// Subscribe
const unsubscribeOpen = voltai.on('widget:open', handleOpen);
const unsubscribeSend = voltai.on('chat:send', handleSend);
// Later, when unmounting
unsubscribeOpen();
unsubscribeSend();
voltai.destroy();
The on() method returns an unsubscribe function. Store it if you need to remove the listener later.