> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Metadata

> Pass custom data from your website to personalize AI behavior and enrich lead webhooks

## Overview

Pass arbitrary JSON metadata when initializing the widget to:

* **Personalize the AI assistant** using Data-Driven Rules
* **Track users** across your CRM systems via lead webhooks

## Basic Usage

```javascript theme={null}
window.initChatWidgetMagic({
  widget_key: 'your_widget_key',
  apiUrl: 'https://api.vaile.ai/api/assistant',
  customMetadata: {
    isAuthenticated: false,
    customerType: 'first_time',
    membershipTier: 'premium',
    leadSource: 'google'
  }
});
```

## Hot Reload

Update metadata when users log in or state changes:

```javascript theme={null}
// After user logs in
window.updateCustomMetadata({
  isAuthenticated: true,
  customerType: 'returning'
});
```

<Info>
  Chat history is preserved when updating metadata mid-session. The AI will adapt its behavior based on the new values.
</Info>

## Data-Driven Rules

Custom metadata powers **Data-Driven Rules** - a feature that lets you customize the AI assistant's behavior based on visitor context.

### How It Works

1. Pass metadata fields from your website (e.g., `isAuthenticated`, `customerType`)
2. Configure rules in the [AI Playbook](/installation/ai-playbook) dashboard
3. The AI automatically adapts its responses based on the metadata values

### Predefined Fields

These fields have built-in example instructions in the dashboard:

| Field             | Type    | Example Values                          |
| ----------------- | ------- | --------------------------------------- |
| `isAuthenticated` | boolean | `true`, `false`                         |
| `customerType`    | string  | `first_time`, `returning`, `trade_in`   |
| `membershipTier`  | string  | `basic`, `premium`, `vip`               |
| `leadSource`      | string  | `google`, `facebook`, `referral`        |
| `customerJourney` | string  | `research`, `consideration`, `decision` |

### Custom Fields

You can use any field name you like. Configure a "Custom field" rule in the AI Playbook to use it.

```javascript theme={null}
window.initChatWidgetMagic({
  widget_key: 'your_widget_key',
  customMetadata: {
    internal_segment: 'high-value',
    campaign_code: 'SUMMER2025'
  }
});
```

### Example: Authentication Prompt

**Rule configuration:**

* Field: `isAuthenticated`
* Instructions: "If false, after they've sent 3 messages, politely suggest logging in to save their conversation. If true, don't mention logging in."

**Website integration:**

```javascript theme={null}
// Initial load - user not logged in
window.initChatWidgetMagic({
  widget_key: 'your_widget_key',
  customMetadata: { isAuthenticated: false }
});

// After login
document.getElementById('login-btn').addEventListener('click', () => {
  // ... login logic ...
  window.updateCustomMetadata({ isAuthenticated: true });
});
```

## Webhook Integration

Metadata also appears in `lead.captured.v1` webhooks for CRM integration:

```json theme={null}
{
  "type": "lead.captured.v1",
  "data": {
    "lead": { ... },
    "contact": { ... },
    "custom_metadata": {
      "isAuthenticated": true,
      "customerType": "returning",
      "membershipTier": "premium"
    }
  }
}
```

## Limitations

| Constraint               | Value                                                          |
| ------------------------ | -------------------------------------------------------------- |
| Maximum size             | 10KB                                                           |
| Blocked keys             | `password`, `token`, `api_key`, `secret`, `ssn`, `credit_card` |
| Max rules per dealership | 10                                                             |
| Max instructions length  | 1000 characters                                                |

<Warning>
  Sensitive keys are automatically stripped server-side. Never send actual passwords or tokens.
</Warning>