Overview
Pass arbitrary JSON metadata when initializing the widget to track users across your CRM systems. This metadata is included in all lead webhooks.
Basic Usage
window.initChatWidgetMagic({
widget_key: 'your_widget_key',
apiUrl: 'https://api.vaile.ai/api/assistant',
customMetadata: {
user_id: '12345',
crm_contact_key: 'CONTACT_ABC',
campaign_id: 'summer_2025'
}
});
Hot Reload
Update metadata when users log in or state changes:
window.updateCustomMetadata({
user_id: '67890',
logged_in_at: new Date().toISOString(),
subscription_tier: 'premium'
});
Chat history is preserved when updating metadata mid-session.
Webhook Integration
Metadata appears in lead.captured.v1 webhooks:
{
"type": "lead.captured.v1",
"data": {
"lead": { ... },
"contact": { ... },
"custom_metadata": {
"user_id": "12345",
"crm_contact_key": "CONTACT_ABC",
"campaign_id": "summer_2025"
}
}
}
Limitations
| Constraint | Value |
|---|
| Maximum size | 10KB |
| Blocked keys | password, token, api_key, secret, ssn, credit_card |
Sensitive keys are automatically stripped server-side. Never send actual passwords or tokens.
