> ## 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.

# Events

> React to widget state changes and chat activity

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:

```javascript theme={null}
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.

```javascript theme={null}
const unsubscribe = voltai.on('widget:open', () => {
  console.log('Chat opened');
});
```

**Returns:** A function to remove the listener.

### off(event, handler?)

Remove event listeners.

```javascript theme={null}
// Remove a specific handler
voltai.off('widget:open', myHandler);

// Remove all handlers for an event
voltai.off('widget:open');
```

## Available events

### Widget 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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
// Subscribe
const unsubscribeOpen = voltai.on('widget:open', handleOpen);
const unsubscribeSend = voltai.on('chat:send', handleSend);

// Later, when unmounting
unsubscribeOpen();
unsubscribeSend();
voltai.destroy();
```

<Tip>
  The `on()` method returns an unsubscribe function. Store it if you need to remove the listener later.
</Tip>