Skip to main content

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.

​
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

  1. Pass metadata fields from your website (e.g., isAuthenticated, customerType)
  2. Configure rules in the 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:
FieldTypeExample Values
isAuthenticatedbooleantrue, false
customerTypestringfirst_time, returning, trade_in
membershipTierstringbasic, premium, vip
leadSourcestringgoogle, facebook, referral
customerJourneystringresearch, 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

ConstraintValue
Maximum size10KB
Blocked keyspassword, token, api_key, secret, ssn, credit_card
Max rules per dealership10
Max instructions length1000 characters
Sensitive keys are automatically stripped server-side. Never send actual passwords or tokens.