Your Dealership

> ## 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. # Widget Installation > Detailed guide for installing the Vaile chat widget on your website ## 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](https://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 `` tag: ```html theme={null} ``` Replace `YOUR_WIDGET_KEY` with your actual widget key from the dashboard ## Platform-Specific Instructions ### Method 1: Theme Editor 1. Go to **Appearance** → **Theme Editor** 2. Select **footer.php** 3. Add the widget script before `` 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 1. Go to **Settings** → **Custom Code** 2. Click **Add Custom Code** 3. Paste the widget script 4. Set: * **Add Code to Pages**: All pages * **Place Code in**: Body - end 5. Click **Apply** 1. Go to **Settings** → **Advanced** → **Code Injection** 2. Scroll to **Footer** section 3. Paste the widget script 4. Click **Save** Code Injection requires a Business plan or higher 1. Go to **Online Store** → **Themes** 2. Click **Actions** → **Edit code** 3. Open **theme.liquid** under Layout 4. Find `` tag 5. Paste the widget script above it 6. Click **Save** For static HTML sites, add the script directly: ```html theme={null} Your Dealership ``` ## 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: ```javascript theme={null} 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: ```javascript theme={null} // 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'); ``` ### Checking Widget Status If you're using custom buttons or elements to trigger the chat, you should check the widget status to conditionally show/hide them. This is especially important if you've disabled the widget in your dashboard settings. ```javascript theme={null} // Check widget status: "loading" | "ready" | "disabled" | "error" console.log(window.chatWidgetMagicStatus); // Example: Conditionally show/hide a custom chat button function updateChatButton() { const myButton = document.getElementById('my-chat-button'); if (window.chatWidgetMagicStatus === 'ready') { myButton.style.display = 'block'; } else if (window.chatWidgetMagicStatus === 'disabled') { myButton.style.display = 'none'; } else if (window.chatWidgetMagicStatus === 'loading') { // Still loading, check again shortly setTimeout(updateChatButton, 100); } } // Run after widget script loads updateChatButton(); ``` The status values are: * **loading**: Widget is still initializing * **ready**: Widget is active and can be controlled * **disabled**: Widget has been turned off in your dashboard * **error**: Widget failed to initialize (check console for details) ### Use Cases Open chat with pre-filled message from vehicle detail pages: ```html theme={null} ``` Trigger chat from service appointment buttons: ```javascript theme={null} document.getElementById('book-service').addEventListener('click', () => { window.openChatWidgetMagic(); setTimeout(() => { window.sendChatMessage('I need to schedule a service appointment'); }, 500); }); ``` Open chat based on user behavior: ```javascript theme={null} // Open chat after viewing 3 inventory pages let pageViews = parseInt(sessionStorage.getItem('inventoryViews') || 0); if (pageViews >= 3 && !sessionStorage.getItem('chatOpened')) { window.openChatWidgetMagic(); sessionStorage.setItem('chatOpened', 'true'); } ``` 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 `` 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 Customize the widget appearance and behavior Ensure everything is working correctly ## Need Help? If you're experiencing installation issues: * Email: [support@vaile.ai](mailto:support@vaile.ai) * Dashboard: Live chat support * Documentation: [Troubleshooting Guide](/widget/troubleshooting)