Custom Metadata

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

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:

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

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

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

Pass metadata fields from your website (e.g., isAuthenticated, customerType)
Configure rules in the AI Playbook dashboard
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.

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:

// 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:

{
  "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

Sensitive keys are automatically stripped server-side. Never send actual passwords or tokens.

Getting Started

Installation & Setup

Setup & Configuration

Integrations

Overview

Basic Usage

Hot Reload

Data-Driven Rules

How It Works

Predefined Fields

Custom Fields

Example: Authentication Prompt

Webhook Integration

Limitations

​Overview

​Basic Usage

​Hot Reload

​Data-Driven Rules

​How It Works

​Predefined Fields

​Custom Fields

​Example: Authentication Prompt

​Webhook Integration

​Limitations

Overview

Basic Usage

Hot Reload

Data-Driven Rules

How It Works

Predefined Fields

Custom Fields

Example: Authentication Prompt

Webhook Integration

Limitations