# Advanced Usage

## Multiple Widget Instances

You can open multiple widget instances simultaneously, each with different configurations:

```javascript
const supportWidget = await MailAgent.open({
  bottom: "20px",
  right: "20px",
  width: "350px",
  height: "500px"
});

const feedbackWidget = await MailAgent.open({
  path: "/feedback",
  bottom: "20px",
  left: "20px",
  width: "350px",
  height: "400px"
});
```

## Dynamic User Switching

If your application supports multiple users or accounts, load the script once and pass different user IDs when opening:

```javascript
// The data-user-id on the script tag is the default.
// You can override it in the init flow via postMessage if needed.
```

## Analytics Integration

Pass a `distinctId` to associate widget analytics with your own user tracking:

```javascript
const widget = await MailAgent.open({
  bottom: "20px",
  right: "20px",
  width: "400px",
  height: "600px",
  distinctId: currentUser.analyticsId
});
```

This ID is forwarded to the analytics system (PostHog) so you can correlate widget usage with your own user metrics.

## Programmatic Messaging

Use `widget.send()` to trigger contextual conversations based on user actions in your app:

```javascript
// User clicks a "Help" button next to an order
widget.send({
  text: `Help me write a follow-up email about order #${orderId}`
});

// User selects a template
widget.send({
  text: "Draft an email using the 'Meeting Request' template"
});
```

## Lifecycle Management

The widget handle gives you control over the widget lifecycle:

```javascript
const widget = await MailAgent.open({ /* ... */ });

// Check if still in DOM
console.log(widget.mounted); // true

// Close the widget
widget.unmount();

// After unmount completes
console.log(widget.mounted); // false
```

The `unmount()` method plays a fade-out animation before removing the iframe. The widget handle becomes invalid after unmounting.

## Chat Persistence

The widget automatically persists chat history in the browser using `localForage`. Messages are stored for **24 hours** and will be restored if the user reopens the widget within that window.

This means:

* Users can close and reopen the widget without losing context.
* Refreshing the page preserves the conversation.
* After 24 hours, the chat history is automatically cleared.

## Feedback Page

The widget includes a built-in feedback page at the `/feedback` route:

```javascript
const feedbackWidget = await MailAgent.open({
  path: "/feedback",
  bottom: "20px",
  right: "20px",
  width: "400px",
  height: "500px"
});
```

## Language Detection

The widget automatically detects the user's browser language (`navigator.language`) and sends it with each message. The AI assistant will respond in the same language when possible. 22+ languages are supported, including:

English, Spanish, French, German, Arabic, Chinese, Japanese, Korean, Portuguese, Russian, Italian, Dutch, Polish, Turkish, Vietnamese, Thai, Indonesian, Hindi, Bengali, Swedish, Danish, and Norwegian.