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.
