Skip to main content

​
Overview

This comprehensive guide covers all aspects of installing the Vaile chat widget on your dealership website, including advanced configurations and platform-specific instructions.

​
Basic Installation

​
Step 1: Obtain Your Widget Key

Your widget key uniquely identifies your dealership and connects the chat widget to your account.
  1. Log in to app.vaile.ai
  2. Navigate to Setup → Installation
  3. Click Copy Widget Key
Keep your widget key secure. It’s unique to your dealership and should not be shared publicly.

​
Step 2: Add the Widget Script

Add this code to your website, just before the closing </body> tag: 
<!-- Vaile Chat Widget -->
<script src="https://embed.vaile.ai/chat-widget-magic.iife.js"></script>
<script>
  initChatWidgetMagic({
    widget_key: 'YOUR_WIDGET_KEY',
    apiUrl: 'https://api.vaile.ai/api/assistant'
  });
</script>
Replace YOUR_WIDGET_KEY with your actual widget key from the dashboard

​
Platform-Specific Instructions

  • WordPress
  • Wix
  • Squarespace
  • Shopify
  • Custom HTML

​
Method 1: Theme Editor

  1. Go to Appearance → Theme Editor
  2. Select footer.php
  3. Add the widget script before </body>
  4. Click Update File

​
Method 2: Plugin

  1. Install “Insert Headers and Footers” plugin
  2. Go to Settings → Insert Headers and Footers
  3. Paste the widget script in the Footer section
  4. Save changes
Using a plugin is recommended as it persists through theme updates

​
Advanced Configuration

The chat widget is positioned at the bottom-right corner by default and cannot be repositioned.

​
Hide Chat Bubble

To hide the default chat bubble (useful if you’re triggering the chat programmatically), add the showBubble: false option: 
initChatWidgetMagic({
  widget_key: 'YOUR_WIDGET_KEY',
  apiUrl: 'https://api.vaile.ai/api/assistant',
  showBubble: false  // Hide the bubble - chat only opens programmatically
});
When to use this:
  • Building custom triggers or buttons to open chat
  • Integrating chat into your own UI elements
  • Opening chat based on user behavior or events
When the bubble is hidden, users can only open the chat through your custom implementation using window.openChatWidgetMagic().

​
Programmatic Control

​
JavaScript API

Control the widget programmatically from your website code: 
// Open the chat widget
window.openChatWidgetMagic();

// Close the chat widget
window.closeChatWidgetMagic();

// Toggle the chat widget
window._chatWidgetMagicInstance?.toggle();

// Send a message programmatically
window.sendChatMessage('Tell me about this vehicle');

​
Use Cases

  • Vehicle Inquiry
  • Service Booking
  • Custom Triggers
Open chat with pre-filled message from vehicle detail pages:
<button onclick="inquireAboutVehicle('VIN12345')">
  Inquire About This Vehicle
</button>

<script>
function inquireAboutVehicle(vin) {
  window.openChatWidgetMagic();
  setTimeout(() => {
    window.sendChatMessage(`I'm interested in vehicle ${vin}`);
  }, 500);
}
</script>
Add a 500ms delay after opening the widget before sending a message to ensure proper initialization

​
Verification & Testing

​
1. Visual Verification

After installation, you should see:
  • Chat icon in the corner of your website
  • Smooth animation when clicking the icon
  • Your customized greeting message

​
2. Console Check

Open browser DevTools (F12) and check for:
  • No error messages related to Vaile
  • Successful widget initialization message

​
3. Functionality Test

  1. Click the chat icon
  2. Type a test message
  3. Verify you receive an AI response
  4. Check your dashboard for the test conversation

​
Common Issues

Solutions:
  • Verify the widget key is correct
  • Check for JavaScript errors in console
  • Ensure script is before </body> tag
  • Clear browser cache
  • Disable ad blockers temporarily
Solutions:
  • Check your Vaile account is active
  • Verify widget key permissions
  • Ensure cookies are enabled
  • Check browser console for errors
Solutions:
  • Ensure viewport meta tag is present
  • Check for CSS conflicts
  • Test in different mobile browsers
  • Update to latest widget version
Solutions:
  • Use defer attribute (included by default)
  • Implement delayed loading if needed
  • Check for other slow scripts
  • Use browser performance profiler

​
Security Considerations

  • The widget runs in an isolated iframe
  • No access to parent page data
  • All communications are encrypted (HTTPS)
  • No sensitive data is stored locally
The Vaile widget is designed with security and privacy in mind, ensuring safe operation on your website

​
CORS & Website Configuration

Important: For security, the widget only works on domains you explicitly allow. When you add your dealership website in Profile Settings, Vaile automatically configures the following CORS origins:
  • https://yourdomain.com (base domain)
  • https://www.yourdomain.com (www subdomain)
  • https://*.yourdomain.com (all subdomains)
The “Test Your Assistant” button in the dashboard will not work until you configure your website URL in Profile Settings. This is a security feature to prevent unauthorized widget usage.
What this means:
  • Add your website URL in Profile Settings before testing
  • The widget will automatically work on all your subdomains
  • Manual CORS entries are preserved when updating your website
  • Localhost and IP addresses are excluded for security

​
Next Steps

Configure Settings

Customize the widget appearance and behavior

Test Your Setup

Ensure everything is working correctly

​
Need Help?

If you’re experiencing installation issues: