🚀 xsukax WhatsApp Widget

A lightweight, privacy-focused JavaScript library for adding WhatsApp chat functionality to any website with a single line of code. No dependencies, no tracking, no external API calls except to WhatsApp itself.

Live Demo | GitHub Repository

📋 Project Overview

The xsukax WhatsApp Widget is a standalone JavaScript solution that enables website owners to integrate a WhatsApp chat interface directly into their web pages. Unlike third-party chat services that require account registration, backend infrastructure, or monthly subscriptions, this widget provides a self-hosted, zero-configuration alternative that maintains complete control over your user interactions.

The widget creates an elegant, WhatsApp-style chat interface that allows visitors to compose messages before being redirected to the official WhatsApp platform. This approach ensures seamless conversation continuity while maintaining the familiar WhatsApp user experience.

Key Characteristics:

Self-contained: Single JavaScript file with embedded CSS and SVG assets
Zero dependencies: No external libraries or frameworks required
Client-side only: No server-side processing or database requirements
Universal compatibility: Works with any website platform (WordPress, Shopify, static HTML, etc.)
Minimal footprint: Approximately 8KB minified, with no runtime overhead

🔒 Security and Privacy Benefits

This widget has been designed with a privacy-first approach to protect both website owners and their visitors:

Client-Side Architecture

All widget functionality executes entirely in the visitor's browser. No user data is transmitted to third-party servers, logged externally, or stored in remote databases. The only external communication occurs when a visitor chooses to send a message, at which point they are redirected to WhatsApp's official platform using the standard api.whatsapp.com endpoint.

No Tracking or Analytics

The widget does not implement any analytics, tracking pixels, fingerprinting techniques, or telemetry. Visitor interactions with the chat interface remain completely private and are not monitored, recorded, or transmitted anywhere except to the intended WhatsApp recipient when the visitor explicitly sends a message.

Input Sanitization

All user-provided text is automatically sanitized using HTML escaping to prevent Cross-Site Scripting (XSS) attacks. The widget creates text nodes programmatically and encodes special characters before rendering any user input, ensuring that malicious scripts cannot be injected into the chat interface.

Message Length Limits

Input fields are constrained to a maximum of 500 characters to prevent potential buffer overflow attempts and to align with WhatsApp's message size recommendations. This limitation protects both the widget's performance and prevents abuse vectors.

Secure URL Construction

WhatsApp URLs are constructed using standard encodeURIComponent() encoding to ensure that special characters in messages do not break the URL structure or introduce injection vulnerabilities. Phone numbers are validated using regex patterns to accept only numeric input, preventing malformed or malicious phone number submissions.

No External Resource Dependencies

All visual assets (icons, fonts, patterns) are embedded directly within the JavaScript file as inline SVG or data URIs. This eliminates the risk of third-party CDN compromises, supply chain attacks, or external resource manipulation that could occur if dependencies were loaded from remote sources.

Content Security Policy (CSP) Compatible

The widget is designed to function within restrictive Content Security Policy environments. Since it injects styles programmatically and does not rely on eval() or inline event handlers, it can operate safely in CSP-compliant contexts with appropriate configurations.

Transparent Operation

The widget's source code is fully open and auditable. The GPL-3.0 license ensures that any modifications or derivatives remain transparent, allowing security-conscious website owners to review and verify the widget's behavior before deployment.

✨ Features and Advantages

Unique Selling Points

One-Line Installation: Add a single <script> tag to your website—no configuration files, build processes, or package managers required
100% Self-Hosted: Complete control over your chat infrastructure without dependence on third-party services
WhatsApp-Native Experience: Authentic WhatsApp-style interface with message bubbles, timestamps, and familiar visual design
Zero Cost: No subscription fees, usage limits, or premium tiers—completely free and open source
Instant Setup: Functional in under 60 seconds from download to live deployment
Responsive Design: Automatically adapts to desktop, tablet, and mobile devices with optimized layouts

Customization Capabilities

Flexible Positioning: Place the chat button on the left or right side of the screen
Brand Alignment: Customize button colors to match your website's color scheme
Multilingual Support: Configure greeting messages and placeholders in any language
Auto-Engagement: Optional auto-open functionality with configurable delay timers
Size Adjustment: Modify button dimensions to suit different design aesthetics

User Experience Enhancements

Smooth Animations: Subtle fade-in, slide-up, and pulse effects for professional polish
Keyboard Navigation: Full support for Enter key submission and Escape key dismissal
Visual Feedback: Hover states, focus indicators, and transition effects for intuitive interaction
Message Preview: Allow visitors to compose and review messages before committing to WhatsApp
Timestamp Display: Real-time timestamp generation for each message exchange
Business Avatar: Automatic initial generation from business name for brand recognition

Technical Advantages

Vanilla JavaScript: Written in pure JavaScript (ES6+) without framework dependencies
Modern Browser APIs: Leverages current web standards while maintaining broad compatibility
IIFE Pattern: Immediately Invoked Function Expression prevents global namespace pollution
Graceful Degradation: Validates configuration and fails safely with console error messages
Performance Optimized: Minimal DOM manipulation and efficient event delegation
Mobile-First CSS: Media queries ensure optimal rendering on smaller screens

🛠️ Installation Instructions

Prerequisites

A website with HTML access (static site, CMS, or web application)
A WhatsApp phone number with country code (no need for WhatsApp Business API)
Modern web browser (Chrome 60+, Firefox 60+, Safari 12+, Edge 79+)

Installation Methods

You can install the widget using either the CDN method (recommended for quick setup) or by self-hosting the file.

Method 1: CDN Installation (Recommended)

No downloads required! Simply add this single line to your HTML before the closing </body> tag:

<script src="https://cdn.jsdelivr.net/gh/xsukax/xsukax-WhatsApp-Widget@main/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Your Business Name"></script>

Alternative CDN Options:

Using GitHub Raw (Direct from repository):

<script src="https://raw.githubusercontent.com/xsukax/xsukax-WhatsApp-Widget/main/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Your Business Name"></script>

CDN Advantages:

✅ No file uploads required
✅ Automatic updates (when using @main)
✅ Global CDN distribution for faster loading
✅ Reduced server bandwidth usage
✅ Works immediately on any platform

Replace:

1234567890 with your WhatsApp number (country code + number, no + symbol)
Your Business Name with your business or contact name

Method 2: Self-Hosted Installation

Step 1: Download the Widget

Download the xsukax-whatsapp-widget.js file from the GitHub repository or clone the repository:

git clone https://github.com/xsukax/xsukax-WhatsApp-Widget.git

Step 2: Upload to Your Server

Upload xsukax-whatsapp-widget.js to your website's directory. Common locations include:

/js/xsukax-whatsapp-widget.js
/assets/js/xsukax-whatsapp-widget.js
/public/xsukax-whatsapp-widget.js

Step 3: Add the Script Tag

Insert the following code before the closing </body> tag in your HTML:

<script src="path/to/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Your Business Name"></script>

Replace:

path/to/ with the actual path to the JavaScript file
1234567890 with your WhatsApp number (country code + number, no + symbol)
Your Business Name with your business or contact name

Self-Hosted Advantages:

✅ Complete control over updates
✅ No external dependencies
✅ Works offline or in restricted environments
✅ Custom modifications possible

Verify Installation

Reload your webpage. You should see a green WhatsApp button appear in the bottom-right corner with a pulsing animation. Click it to test the chat interface.

Platform-Specific Installation

WordPress

Option A: Using CDN (Easiest)

Navigate to Appearance → Theme Editor → footer.php
Add before <?php wp_footer(); ?>:

<script src="https://cdn.jsdelivr.net/gh/xsukax/xsukax-WhatsApp-Widget@main/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Your Store"></script>

Option B: Self-Hosted

Upload the JavaScript file via Media → Add New
Copy the file URL
Navigate to Appearance → Theme Editor → footer.php
Add the script tag before <?php wp_footer(); ?>

Shopify

Option A: Using CDN (Easiest)

Go to Online Store → Themes → Actions → Edit Code
Edit theme.liquid and add before </body>:

<script src="https://cdn.jsdelivr.net/gh/xsukax/xsukax-WhatsApp-Widget@main/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Your Store"></script>

Option B: Self-Hosted

Go to Online Store → Themes → Actions → Edit Code
Upload xsukax-whatsapp-widget.js to the Assets folder
Edit theme.liquid and add before </body>:

<script src="{{ 'xsukax-whatsapp-widget.js' | asset_url }}" 
        data-phone="1234567890" 
        data-title="Your Store"></script>

Static HTML

Using CDN:

<script src="https://cdn.jsdelivr.net/gh/xsukax/xsukax-WhatsApp-Widget@main/xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Business Name"></script>

Self-Hosted:

<script src="xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Business Name"></script>

CDN vs Self-Hosted: Which Should You Choose?

Feature	CDN (jsDelivr/GitHub)	Self-Hosted
Setup Time	Instant (copy-paste)	2-5 minutes
File Management	None required	Manual uploads
Updates	Automatic (with `@main`)	Manual
Control	Limited	Full control
Customization	Not possible	Can modify code
Offline Support	Requires internet	Works offline
Performance	Global CDN (fast)	Depends on your server
Privacy	External request	Fully self-contained

Recommendation:

Use CDN if you want quick setup and automatic updates
Use Self-Hosted if you need custom modifications or maximum privacy

📖 Usage Guide

Basic Configuration

The widget is configured entirely through HTML5 data attributes on the <script> tag:

<script src="xsukax-whatsapp-widget.js" 
        data-phone="1234567890" 
        data-title="Tech Support"
        data-greeting="Hello! How can we help you today?"
        data-position="right"></script>

Complete Configuration Reference

Attribute	Description	Default Value	Required
`data-phone`	WhatsApp phone number with country code (digits only, no +)	—	✅ Yes
`data-title`	Business name displayed in chat header	`"Business"`	❌ No
`data-position`	Button position: `"right"` or `"left"`	`"right"`	❌ No
`data-button-size`	Button diameter in pixels	`"60"`	❌ No
`data-button-color`	Button background color (hex code)	`"#25d366"`	❌ No
`data-greeting`	Initial greeting message from business	`"Hi! 👋 How can I help you today?"`	❌ No
`data-placeholder`	Input field placeholder text	`"Type a message..."`	❌ No
`data-auto-show`	Auto-open chat on page load: `"true"` or `"false"`	`"false"`	❌ No
`data-auto-show-delay`	Milliseconds to wait before auto-opening	`"3000"`	❌ No

Advanced Examples

Full Customization

<script src="xsukax-whatsapp-widget.js" 
        data-phone="201234567890"
        data-title="Acme Corporation"
        data-position="left"
        data-button-size="70"
        data-button-color="#0088cc"
        data-greeting="Welcome to Acme! 🎉 How may we assist you?"
        data-placeholder="Ask us anything..."
        data-auto-show="true"
        data-auto-show-delay="5000"></script>

Multilingual Configuration

<!-- Spanish -->
<script src="xsukax-whatsapp-widget.js" 
        data-phone="34612345678"
        data-title="Soporte al Cliente"
        data-greeting="¡Hola! 👋 ¿Cómo podemos ayudarte?"
        data-placeholder="Escribe un mensaje..."></script>

<!-- French -->
<script src="xsukax-whatsapp-widget.js" 
        data-phone="33612345678"
        data-title="Service Client"
        data-greeting="Bonjour! 👋 Comment puis-je vous aider?"
        data-placeholder="Tapez un message..."></script>

JavaScript API

Control the widget programmatically using the global xsukaxWhatsAppWidget object:

Open the Chat Interface

// Open the chat modal
xsukaxWhatsAppWidget.open();

// Example: Open chat when user clicks a button
document.getElementById('contact-btn').addEventListener('click', function() {
    xsukaxWhatsAppWidget.open();
});

Close the Chat Interface

// Close the chat modal
xsukaxWhatsAppWidget.close();

Access Configuration

// Retrieve current configuration
const config = xsukaxWhatsAppWidget.config;
console.log('Phone:', config.phone);
console.log('Title:', config.title);
console.log('Position:', config.position);

User Interaction Flow

graph TD
    A[Visitor Lands on Website] --> B{Widget Auto-Show Enabled?}
    B -->|Yes| C[Chat Opens After Delay]
    B -->|No| D[Visitor Sees Pulsing WhatsApp Button]
    C --> E[Visitor Sees Greeting Message]
    D --> F[Visitor Clicks Button]
    F --> E
    E --> G[Visitor Types Message]
    G --> H[Visitor Clicks Send]
    H --> I[Message Appears in Chat]
    I --> J[System Shows Opening WhatsApp Message]
    J --> K[WhatsApp Opens in New Tab]
    K --> L[Message Pre-Filled in WhatsApp]
    L --> M[Conversation Continues in WhatsApp]

Architecture Overview

graph LR
    A[Website HTML] --> B[xsukax-whatsapp-widget.js]
    B --> C[Configuration Parser]
    C --> D[Phone Validation]
    D --> E{Valid?}
    E -->|No| F[Console Error]
    E -->|Yes| G[Style Injection]
    G --> H[DOM Element Creation]
    H --> I[Event Listeners]
    I --> J[Public API Exposure]
    J --> K[Widget Active]
    K --> L[User Interaction]
    L --> M[WhatsApp API Call]

Common Use Cases

E-Commerce Support

<script src="xsukax-whatsapp-widget.js" 
        data-phone="1234567890"
        data-title="Sales Support"
        data-greeting="Hi! 🛍️ Need help with your order?"
        data-button-color="#FF6B6B"></script>

Real Estate Inquiries

<script src="xsukax-whatsapp-widget.js" 
        data-phone="1234567890"
        data-title="Property Agent"
        data-greeting="Hello! 🏡 Interested in a property?"
        data-auto-show="true"
        data-auto-show-delay="8000"></script>

Customer Service

<script src="xsukax-whatsapp-widget.js" 
        data-phone="1234567890"
        data-title="24/7 Support"
        data-greeting="Welcome! 💬 We're here to help anytime."
        data-position="left"></script>

Troubleshooting

Widget Not Appearing:

Verify the JavaScript file path is correct (or CDN URL is accessible)
Check browser console for error messages
Ensure data-phone attribute contains only digits
Confirm script tag is placed before </body>
If using CDN, verify internet connection and that CDN is not blocked

CDN Loading Issues:

Check if jsDelivr or GitHub is blocked by your network/firewall
Try alternative CDN URL (GitHub Raw vs jsDelivr)
Consider self-hosting if CDN is unreliable in your region
Test CDN URL directly in browser: https://cdn.jsdelivr.net/gh/xsukax/xsukax-WhatsApp-Widget@main/xsukax-whatsapp-widget.js

Chat Not Opening WhatsApp:

Verify phone number includes country code
Test phone number format: country code + number (e.g., 12025551234)
Check browser popup blockers
Ensure WhatsApp is installed or WhatsApp Web is accessible

Styling Conflicts:

The widget uses a xsukax-wa- class prefix to avoid CSS conflicts
If issues persist, check for global CSS resets affecting position or z-index
Verify no CSP policies blocking inline styles

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

Development Setup

# Clone the repository
git clone https://github.com/xsukax/xsukax-WhatsApp-Widget.git

# Navigate to directory
cd xsukax-WhatsApp-Widget

# Open index.html in browser for testing
# Modify xsukax-whatsapp-widget.js as needed

🌟 Support

If you find this project useful, please consider:

⭐ Starring the repository on GitHub
🐛 Reporting bugs or suggesting features
📢 Sharing with others who might benefit

📞 Contact

Author: xsukax
GitHub: @xsukax
Repository: xsukax-WhatsApp-Widget

📚 Additional Notes

Browser Compatibility

Chrome 60+ ✅
Firefox 60+ ✅
Safari 12+ ✅
Edge 79+ ✅
Opera 47+ ✅
Mobile browsers (iOS Safari, Chrome Mobile) ✅

Performance Considerations

Widget adds approximately 8KB to page load
No additional HTTP requests (self-contained)
Minimal JavaScript execution time (<10ms)
CSS injected once on initialization
No continuous background processes

Privacy Recommendations

For enhanced privacy when using this widget:

Inform visitors about WhatsApp integration in your privacy policy
Consider adding a disclaimer that clicking "Send" redirects to WhatsApp
Do not store or log messages typed in the widget interface
Respect regional data protection regulations (GDPR, CCPA, etc.)

WhatsApp Business Integration

While this widget works with standard WhatsApp numbers, pairing it with a WhatsApp Business account provides:

Automated greeting messages
Quick replies and away messages
Business profile with address and hours
Message statistics and labels

Made with ❤️ by xsukax | Free & Open Source

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
LICENSE		LICENSE
README.md		README.md
index.html		index.html
xsukax-whatsapp-widget.js		xsukax-whatsapp-widget.js

Folders and files

Latest commit

History

Repository files navigation