# Configuration

The widget can be configured in two ways: via **data attributes** on the script tag (static config) and via the **JavaScript API** when opening the widget (dynamic config).

## Script Tag Attributes

These are set as `data-*` attributes on the `<script>` tag and apply globally.

| Attribute                       | Type      | Required | Description                                     |
| ------------------------------- | --------- | -------- | ----------------------------------------------- |
| `data-user-id`                  | `string`  | Yes      | Your MailAgent user ID.                         |
| `data-suggestions`              | `JSON`    | No       | Array of quick-action suggestions.              |
| `data-header-transparent`       | `boolean` | No       | Set to `"true"` to make the header transparent. |
| `data-color-background-primary` | `string`  | No       | Primary background color (hex code).            |

### Suggestions Format

Suggestions appear as clickable quick-action buttons in the chat. Each suggestion has an icon and text:

```html
<script
  src="https://widget.mailagent.email/connect/connect.js"
  data-user-id="YOUR_USER_ID"
  data-suggestions='[
    {"icon": "✉️", "text": "Write a professional email"},
    {"icon": "📝", "text": "Summarize this thread"},
    {"icon": "🔍", "text": "Find relevant information"},
    {"icon": "💬", "text": "Draft a reply"}
  ]'
></script>
```

| Field  | Type     | Required | Description                                              |
| ------ | -------- | -------- | -------------------------------------------------------- |
| `icon` | `string` | No       | An emoji or short string shown as icon.                  |
| `text` | `string` | Yes      | The suggestion text (also sent as message when clicked). |

## Open Options

These are passed to `MailAgent.open()` and can differ each time the widget is opened:

```javascript
const widget = await MailAgent.open({
  path: "/",
  top: "20px",
  right: "20px",
  width: "400px",
  height: "600px",
  distinctId: "user_analytics_id"
});
```

| Option       | Type     | Default | Description                                                                 |
| ------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `path`       | `string` | `"/"`   | Route within the widget (e.g., `"/"` for chat, `"/feedback"` for feedback). |
| `top`        | `string` | —       | CSS `top` position (e.g., `"20px"`).                                        |
| `left`       | `string` | —       | CSS `left` position.                                                        |
| `right`      | `string` | —       | CSS `right` position.                                                       |
| `bottom`     | `string` | —       | CSS `bottom` position.                                                      |
| `width`      | `string` | —       | Fixed width. Omit for auto-resize.                                          |
| `height`     | `string` | —       | Fixed height. Omit for auto-resize.                                         |
| `distinctId` | `string` | —       | Analytics identifier for the current visitor.                               |

### Auto-Resize

If you omit `width` and `height`, the widget will automatically resize to fit its content. The widget communicates its dimensions to the parent page via `postMessage`.

```javascript
// Auto-resize mode — widget adjusts to content
const widget = await MailAgent.open({
  bottom: "20px",
  right: "20px"
});
```

### Fixed Size

If you provide both `width` and `height`, the widget will be fixed at those dimensions with internal scrolling.

```javascript
// Fixed size mode
const widget = await MailAgent.open({
  bottom: "20px",
  right: "20px",
  width: "400px",
  height: "600px"
});
```