# Msg91 for WooCommerce

Contributors: MSG91  
Tags: woocommerce, sms, msg91, notifications, chatbot, whatsapp, ai-assistant, product-search, discounts, cart-api  
Requires at least: 5.0  
Tested up to: 7.0  
Stable tag: 2.1.0  
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI-powered shopping assistant with WhatsApp & Web chatbot, product search, cart management, COD-to-prepaid conversion, and SMS notifications via MSG91 for WooCommerce events.

## Description

The **MSG91 for WooCommerce** plugin is an AI-powered shopping assistant that combines automated SMS notifications, a Web Chatbot, and a WhatsApp Bot to drive conversational commerce.

Customers can search products using natural language ("cheap shirts under 999", "top selling products"), manage their cart, apply discounts, and complete checkout — all via chat. The plugin exposes a full REST API (VoiceBot API) that powers bot integrations, and includes a tokenized checkout hand-off so users can move seamlessly from WhatsApp to the browser.

For Cash-on-Delivery orders, the plugin can automatically reach out via WhatsApp and offer customers a discount to convert to prepaid — reducing fulfillment risk and improving cash flow.

Administrators configure channels, discount rules, bot tokens, COD conversion strategies, and automation triggers from a single settings panel.

## Features

- **Automated SMS Notifications** for WooCommerce events via MSG91.
- **AI Chatbot / VoiceBot API** — REST endpoints for natural-language product search, cart CRUD, discount application, checkout, and order placement.
- **WhatsApp Bot** — assisted selling and discount support over WhatsApp with deterministic session handling.
- **Web Chat Widget** — real-time customer support with WooCommerce customer data sync.
- **Natural-Language Product Search** — fuzzy search with intent parsing (price filters, sorting, category / brand / tag / attribute detection, compare & related products).
- **Runtime Coupon Engine** — auto-generates and applies best-fit discount coupons per channel (web / WhatsApp).
- **Multi-Channel Cart** — unified cart for guest, mobile, and logged-in users with bidirectional sync.
- **Tokenized Checkout** — browser hand-off URL that restores the bot session and cart automatically.
- **Admin Interface** for AuthKey, chat-bot, WhatsApp-bot, automation, and widget settings.
- **COD to Prepaid Conversion** — automatically offer COD customers a discount via WhatsApp to switch to prepaid, with configurable order-update strategies and conversion logs.

## Installation

1. Download the plugin ZIP file.
2. Navigate to **Plugins > Add New** in your WordPress admin panel.
3. Click **Upload Plugin**, select the ZIP file, and click **Install Now**.
4. Activate the plugin.
5. Go to **MSG91 > Settings** to configure the AuthKey.
6. Go to **MSG91 > Chat Bot** to configure the chat bot, WhatsApp bot, and discount rules.
7. Go to **MSG91 > Chat Widget** to configure the web widget token and WhatsApp number.
8. Go to **MSG91 > COD to Prepaid** to enable the conversion flow, choose an order-update strategy, and configure discount rules.

## Supported WooCommerce Events

This plugin triggers SMS notifications for:
- New Customer Registration (`woocommerce_new_customer`)
- Customer Update (`woocommerce_update_customer`)
- New Order Placement (`woocommerce_new_order`)
- Order Update (`woocommerce_update_order`)
- Payment Completion (`woocommerce_payment_complete`)
- Order Completion (`woocommerce_order_status_completed`)
- Order Cancellation (`woocommerce_order_status_cancelled`)
- Order Refund (`woocommerce_order_status_refunded`)

## Chat Widget Features
The MSG91 Chat Widget provides real-time customer support capabilities:

### Widget Configuration Options
- **Widget Token**: Secure token from MSG91 dashboard for widget authentication
- **Enable/Disable**: Toggle widget visibility on your store
- **Launcher Control**: Show or hide the chat launcher button
- **Form Display**: Control whether to show user information collection form
- **Close Button**: Toggle close button visibility
- **Auto Launch**: Automatically open widget when page loads
- **Send Button**: Control send button visibility
- **Delay Timing**: Set custom delay before widget loads (0-10000ms)

### Customer Data Integration
The widget automatically integrates with WooCommerce customer data:
- **User ID**: WordPress user ID for logged-in customers
- **Name**: Customer display name
- **Email**: Customer email address
- **Phone**: Billing phone number from WooCommerce
- **Location**: Country, state, and city from billing address

## AI Product Search

Natural-language queries are parsed for:
- **Price ranges** — "under 999", "between 100 and 500", "above 500"
- **Sorting** — "cheap" (price ASC), "top selling" (total_sales DESC), "newest" (date DESC), "top rated" (rating DESC)
- **Filters** — category, brand, tag, and product attributes (color, size, material, etc.)
- **Intents** — compare ("A vs B"), related ("similar to X"), on-sale, featured / recommended

## COD to Prepaid

Convert Cash-on-Delivery (COD) orders to prepaid via automated WhatsApp outreach.

- **WhatsApp Confirmation** — Send an order-confirmation message immediately after a COD order is placed.
- **Conversion Offer** — Offer a configurable discount to incentivise the customer to pay in advance.
- **Order-Update Strategies** —
  - *Option A*: Tag the original order as "Converted to Prepaid".
  - *Option B*: Tag and cancel the original order, then create a new paid order.
  - *Option C*: Tag the original order and mark it as Paid.
- **Backup Order Type** — Automatically fall back to Option B if the main strategy fails.
- **Discount Rules** — Percentage or fixed-amount discounts with minimum-subtotal and currency filters.
- **Conversion Logs** — Track every conversion attempt, success, failure reason, and discount allocation from **MSG91 > COD to Prepaid Logs**.

### Technical Implementation
- Loads MSG91 chat widget script from `https://blacksea.msg91.com/chat-widget.js`
- Only loads on frontend (not in admin area)
- Respects WordPress security standards with proper nonce verification
- Stores settings securely in WordPress database
- Provides real-time preview of widget configuration

## How to Use

### Setting Up the MSG91 AuthKey
1. Navigate to **MSG91 > Settings**.
2. Enter your **AuthKey**.
3. Select the **Default Country**.
4. Click **Save Auth Settings**.

### Managing Automation Rules
1. Navigate to **MSG91 > Automations**.
2. Add or update automation rules for triggering Campaign notifications via multiple channels.

### Configuring Chat Bot
1. Navigate to **MSG91 > Chat Bot**.
2. In the **Chat Widget** section, enter the **Bot Instructions** to define the AI assistant behaviour.
3. Enable **Assisted Selling** to allow cart operations through the bot.
4. Enable **Discount Support** to let the bot auto-apply runtime coupons.
5. Save settings.

### Configuring WhatsApp Bot
1. Navigate to **MSG91 > Chat Bot**.
2. In the **WhatsApp** section, select the **WhatsApp Number**.
3. Enable **Use Widget Bot** to reuse the chat-widget bot for WhatsApp (instead of creating a separate bot).
4. Enable **Assisted Selling** and **Discount Support** as needed.
5. Save settings.

### Configuring Chat Widget
1. Navigate to **MSG91 > Chat Widget**.
2. Select the **Widget Token** from the dropdown.
3. Configure the **WhatsApp Number** for the widget.
4. Click **Save Settings** or **Preview Widget** to test.

### Configuring COD to Prepaid
1. Navigate to **MSG91 > COD to Prepaid**.
2. Enable the **COD to Prepaid** toggle.
3. Select the **WhatsApp Number** to send confirmation and conversion messages.
4. Choose a **Main Order Type** (Option A, B, or C) that matches your fulfillment workflow.
5. (Optional) Enable **Backup Order Type** to use Option B as a fallback.
6. Enable **COD Confirmation** to send an immediate order-confirmation message.
7. Switch to the **Discount** tab to add conversion discounts (percentage or amount, with minimum subtotal and currency).
8. Save settings.
9. View conversion history and filter logs at **MSG91 > COD to Prepaid Logs**.

## File Storage and Data Management

This plugin follows WordPress.org guidelines for file storage:

### Data Storage Location
- Plugin Data: All plugin-generated files are stored in the WordPress uploads directory at `wp-content/uploads/msg91-for-woocommerce/`
- WordPress Compliance: Ensures compatibility with plugin update guidelines
- Automatic Cleanup: Files are removed when the plugin is uninstalled

### File Operations
The plugin uses the WordPress filesystem API for secure operations:
- Save JSON files in uploads directory
- Read stored JSON files
- Delete files when needed
- Automatic migration of old files to uploads during activation

## External Services
This plugin connects to external services to provide SMS functionality:

### MSG91.com
- Purpose: SMS delivery, chat-bot orchestration, WhatsApp template / campaign management, and inbox linking
- Data sent: User phone numbers, message content, campaign data, bot configuration
- API Endpoints: https://control.msg91.com/api/v5
- Terms of use: https://msg91.com/terms
- Privacy policy: https://msg91.com/privacy

### Additional Services
- **IP Info API**: Used for location-based services (https://ipinfo.io/json)
- **Sokt.io**: Used for flow management (https://flow.sokt.io)

## Support
For any issues, contact support via [GitHub Issues](https://github.com/your-repo/issues) or WooCommerce Support Forums.

== License ==
This plugin is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this plugin; if not, see https://www.gnu.org/licenses/gpl-2.0.html.

## License
This plugin is licensed under the [GPLv2 or later](https://www.gnu.org/licenses/gpl-2.0.html).