CDN Installation Guide
Install the HelloAivy chat widget on any website using a simple CDN script tag.
The CDN installation method allows you to add the chat widget to any website in under 60 seconds using a simple script tag.
Quick Start
Step 1: Get Your Script Tag
Navigate to your chatbot's Publish tab in the HelloAivy dashboard to find your unique script tag. It will look like this:
<script async data-chatbot='YOUR_CHATBOT_ID' src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>
Step 2: Add to Your Website
Paste the script tag just before the closing </body> tag in your HTML:
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<script async data-chatbot='YOUR_CHATBOT_ID' src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>
</body>
</html>
Step 3: Verify Installation
Save your HTML file and open it in a browser. You should see a chat button in the bottom-right corner of your page.
Widget Modes
Floating Mode (Default)
The floating mode displays a chat button in the corner of your website:
<!-- Floating Mode (Bottom Right) --> <script async data-chatbot='YOUR_CHATBOT_ID' src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>
This is the recommended mode for most websites as it's always accessible without taking up page space.
Embedded Mode
Embed the chat interface directly in a container element:
<!-- Embedded Mode --> <div id="helloaivy-chat" style="height: 600px;"></div> <script async data-chatbot='YOUR_CHATBOT_ID' data-mode="embedded" data-target="helloaivy-chat" src='https://helloaivy-widget.vercel.app/chat-widget.js'> </script>
Perfect for dedicated support pages where you want the chat interface to be the main focus.
Customization Options
Custom Theme & Position
Customize the primary color and button position to match your brand:
<!-- Custom Theme --> <script async data-chatbot='YOUR_CHATBOT_ID' data-primary-color="#10b981" data-position="bottom-left" src='https://helloaivy-widget.vercel.app/chat-widget.js'> </script>
Available Data Attributes
| Attribute | Description | Values |
|---|---|---|
data-chatbot | Your chatbot ID (required) | UUID string |
data-mode | Widget display mode | floating or embedded |
data-target | Target element ID for embedded mode | Element ID (string) |
data-position | Button position | bottom-right or bottom-left |
data-primary-color | Theme color | Hex color code (e.g., #10b981) |
data-theme | Color theme | light or dark |
Platform-Specific Instructions
Webflow
- Open your Webflow project settings
- Navigate to Custom Code → Footer Code
- Paste the script tag
- Publish your site
Shopify
- Go to Online Store → Themes
- Click Actions → Edit Code
- Open the
theme.liquidfile - Paste the script before the closing
</body>tag - Save changes
Wix
- Open your Wix Editor
- Click Settings → Custom Code
- Click Add Custom Code
- Paste the script and select "Body - End"
- Apply to all pages and save
Squarespace
- Go to Settings → Advanced → Code Injection
- Paste the script in the Footer section
- Save changes
Webflow
- Open your Webflow project
- Go to Project Settings → Custom Code
- Paste the script in the Footer Code section
- Publish your changes
Custom HTML/Static Sites
Simply add the script tag before the closing </body> tag in your HTML files. For multi-page sites, you may want to include it in a footer template or partial that's shared across all pages.
Advanced Usage
Programmatic Initialization
For advanced use cases, you can initialize the widget programmatically:
<!-- Programmatic API -->
<script>
window.ChatWidgetConfig = {
clientKey: 'YOUR_CHATBOT_ID',
mode: 'floating',
position: 'bottom-right',
theme: 'light',
apiEndpoint: 'API_ENDPOINT_URL',
};
</script>
<script async src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>
This approach gives you more control over the initialization and allows you to dynamically configure the widget based on runtime conditions.
Single Page Applications (SPAs)
For SPAs built with React, Vue, Angular, etc., you can load the widget in your root component or layout:
// React Example
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://helloaivy-widget.vercel.app/chat-widget.js';
script.async = true;
script.setAttribute('data-chatbot', 'YOUR_CHATBOT_ID');
document.body.appendChild(script);
return () => {
document.body.removeChild(script);
};
}, []);
Performance Optimization
The widget is designed for optimal performance:
- Asynchronous Loading: The
asyncattribute ensures the script doesn't block page rendering - Lazy Loading: The chat interface only loads when the user interacts with the button
- Small Bundle Size: The initial script is minimal (~5KB gzipped)
- CDN Delivery: Served from a global CDN for fast loading worldwide
Troubleshooting
Widget Not Appearing
- Check that the script tag is placed before the closing
</body>tag - Verify your chatbot ID is correct
- Check the browser console for any error messages
- Ensure JavaScript is enabled in the browser
- Check for Content Security Policy (CSP) restrictions
Style Conflicts
The widget uses Shadow DOM for complete style isolation, which prevents CSS conflicts with your website. If you're experiencing style issues:
- Check that you haven't disabled Shadow DOM in your browser
- Verify that your site's CSS isn't using
!importantrules that might affect the widget button - Try customizing the widget colors using the
data-primary-colorattribute
Script Loading Issues
If the script fails to load:
- Check your network connection
- Verify the script URL is correct
- Check for browser extensions that might block scripts
- Try disabling ad blockers temporarily
Security Considerations
- The widget script is served over HTTPS
- All API communication is encrypted
- User data is handled according to GDPR standards
- No third-party tracking scripts are included
Next Steps
- Customization Guide - Learn how to customize the widget appearance
- WordPress Installation - Alternative installation method for WordPress sites
Support
If you need assistance with the installation, please contact our support team through the HelloAivy dashboard.