Events

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, firstName, lastName }`
`onChatComplete`	Called when a chat response completes. Receives `{ chatId, chatOutput, chatLink, userEmail, firstName, lastName, 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');
});

Returns: A function to remove the listener.

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, firstName, lastName }`	Message sent by user
`chat:complete`	`{ chatId, chatOutput, chatLink, userEmail, firstName, lastName, 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);
  console.log('First Name:', payload.firstName);
  console.log('Last Name:', payload.lastName);
});

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.
`firstName`	string	Given name of the user. Empty string for guest users or when not provided by the identity provider.
`lastName`	string	Family name of the user. Empty string for guest users or when not provided by the identity provider.

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('First Name:', payload.firstName);
  console.log('Last Name:', payload.lastName);
  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.
`firstName`	string	Given name of the user. Empty string for guest users or when not provided by the identity provider.
`lastName`	string	Family name of the user. Empty string for guest users or when not provided by the identity provider.
`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 flow
intercept 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

If you use 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('User name:', payload.firstName, payload.lastName);
    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('User name:', payload.firstName, payload.lastName);
    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.

Getting Started

Configuration

Guides

Configuration callbacks

Event listener API

on(event, handler)

off(event, handler?)

Available events

Widget events

Chat events

Feedback events

Authentication events

Event payloads

chat:send

chat:complete

auth:ready

auth:login

auth:logout

auth:sign-in-click

auth:sign-out-click

auth:error

feedback:submit

Example: Analytics integration

Example: Chat activity logging

Example: Feedback tracking

Example: Cleanup on unmount

​Configuration callbacks

​Event listener API

​on(event, handler)

​off(event, handler?)

​Available events

​Widget events

​Chat events

​Feedback events

​Authentication events

​Event payloads

​chat:send

​chat:complete

​auth:ready

​auth:login

​auth:logout

​auth:sign-in-click

​auth:sign-out-click

​auth:error

​feedback:submit

​Example: Analytics integration

​Example: Chat activity logging

​Example: Feedback tracking

​Example: Cleanup on unmount

Configuration callbacks

Event listener API

on(event, handler)

off(event, handler?)

Available events

Widget events

Chat events

Feedback events

Authentication events

Event payloads

chat:send

chat:complete

auth:ready

auth:login

auth:logout

auth:sign-in-click

auth:sign-out-click

auth:error

feedback:submit

Example: Analytics integration

Example: Chat activity logging

Example: Feedback tracking

Example: Cleanup on unmount