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 is ready');
},
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 has initialized and authentication is complete |
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 initialized and ready |
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:login | { isGuest } | User logged in |
auth:logout | — | User logged out |
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: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: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.