# AW WhatsApp Widget
[](https://www.npmjs.com/package/@alertwise/aw-whatsapp-widget)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
A zero-dependency, lightweight, and highly configurable WhatsApp chat widget for modern websites. Built with TypeScript for type safety and performance.
## ✨ Features
- 🚀 **Lightweight & Fast:** Zero external dependencies, optimized for minimal performance impact.
- 🎨 **Customizable Themes:** Supports Light, Dark, and Auto (system preference) modes.
- 📍 **Flexible Positioning:** Pin to the bottom-left or bottom-right of your site.
- 👥 **Multiple Agents Support:** Route customers to different departments (e.g., Sales, Support).
- 🕒 **Business Hours:** Show offline messages automatically outside your working hours.
- 📱 **Fully Responsive:** Looks great on both desktop and mobile devices.
- 🌍 **Multi-language Support:** Easily configurable for English, Hindi, and more.
- 📊 **Analytics Integration:** Built-in event tracking for Google Analytics (GA4) and Google Tag Manager (GTM).
---
## 📦 Installation
### Option 1: CDN (Recommended for standard HTML sites)
Include the script directly in your HTML `` or before the closing `` tag:
```html
```
### Option 2: NPM (For React, Vue, Angular, etc.)
```bash
npm install @alertwise/aw-whatsapp-widget
```
---
## 🚀 Usage
### Browser (CDN) Basic Initialization
Once the script is loaded, the `AWWhatsApp` object is available globally.
```html
```
### ES Module / Bundler (NPM)
```javascript
import AWWhatsApp from '@alertwise/aw-whatsapp-widget';
AWWhatsApp.init({
phone: "918888888888",
message: "Hi! I'd like to know more.",
brand: "My Company",
});
```
### Advanced Configuration (Multi-Agent & Business Hours)
```javascript
AWWhatsApp.init({
brand: "Support Team",
theme: "dark",
position: "left",
greetingMessage: "Hi 👋,
How can we help you today?",
agents: [
{ name: "Alice", phone: "911111111111", label: "Sales & Pricing" },
{ name: "Bob", phone: "912222222222", label: "Technical Support" }
],
businessHours: {
timezone: "Asia/Kolkata",
offlineMessage: "We are currently offline. Please leave a message and we will get back to you soon!",
hours: {
mon: [["09:00", "18:00"]],
tue: [["09:00", "18:00"]],
wed: [["09:00", "18:00"]],
thu: [["09:00", "18:00"]],
fri: [["09:00", "18:00"]]
// Omit days like 'sat' and 'sun' to mark them as fully offline
}
},
tracking: {
enabled: true,
gtmEventName: "wa_widget_click"
}
});
```
---
## ⚙️ Configuration API
Here are the properties you can pass to `AWWhatsApp.init(config)`:
| Property | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `phone` | `string` | *Required** | Your WhatsApp number with country code (e.g., "918888888888"). *Not required if using `agents` array.* |
| `brand` | `string` | `"WhatsApp"` | The name displayed in the widget header. |
| `message` | `string` | `""` | The pre-filled message text when the user opens WhatsApp. |
| `greetingMessage`| `string` | `""` | The initial chat bubble text shown inside the widget. |
| `theme` | `string` | `"light"` | Visual theme. Options: `"light"`, `"dark"`, `"auto"`. |
| `position` | `string` | `"right"` | Screen position. Options: `"left"`, `"right"`. |
| `agents` | `Array` | `undefined` | Array of agent objects `{ name, phone, label, avatar }` for multi-department routing. |
| `businessHours` | `Object` | `undefined` | Configuration for availability, timezones, and offline messaging. |
| `tracking` | `Object` | `undefined` | Enable tracking: `{ enabled: true, gtmEventName: 'event_name' }`. |
---
## 🛠️ Development
If you want to contribute or fork the project:
1. Clone the repository:
```bash
git clone [https://github.com/your-org/aw-whatsapp-widget.git](https://github.com/your-org/aw-whatsapp-widget.git)
```
2. Install dependencies:
```bash
npm install
```
3. Run the development server (watches for changes and previews):
```bash
npm run dev
```
4. Build the production files (outputs to `/dist`):
```bash
npm run build
```
---
## 📄 License
This project is licensed under the [MIT License](LICENSE).