# Msg91 for WooCommerce

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

AI-powered shopping assistant with WhatsApp, Web, Facebook & Instagram chatbots, product search, cart management, COD-to-prepaid conversion, refund, returns & exchanges, stock alerts, 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, WhatsApp Bot, Facebook Bot, and Instagram 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.

The plugin also supports automated **Returns & Exchanges** via Bot, allowing customers to initiate returns directly through the bot. Administrators can configure return settings from the admin panel.

**Stock Alerts** notify customers via WhatsApp when out-of-stock products become available again, helping recover lost sales and improve customer retention.

Administrators configure channels, discount rules, bot tokens, COD conversion strategies, return, stock alerts, 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.
- **Returns & Exchanges** — let customers initiate returns via Bot with automated order validation and store credit creation.
- **Stock Alerts** — automatically notify customers via WhatsApp when out-of-stock products are back in stock.
- **Facebook & Instagram Bots** — extend conversational commerce to Facebook Messenger and Instagram DMs with the same AI assistant.

## 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 Widget** to configure the web widget token and WhatsApp number.
7. Go to **MSG91 > Chat Bot** to configure the chat bot, WhatsApp bot, Facebook bot, Instagram bot, Returns & Exchanges and discount rules.
8. Go to **MSG91 > COD to Prepaid** to enable the conversion flow, choose an order-update strategy, and configure discount rules.
9. Go to **MSG91 > Stock Alerts** to enable low-stock WhatsApp alerts and configure the alert number.

## 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 Facebook Bot
1. Navigate to **MSG91 > Chat Bot**.
2. In the **Facebook** section, connect your Facebook page and authorize the MSG91 app.
3. Enable **Assisted Selling** to allow cart operations through Facebook Messenger.
4. Enable **Discount Support** to let the bot auto-apply runtime coupons.
5. Save settings.

### Configuring Instagram Bot
1. Navigate to **MSG91 > Chat Bot**.
2. In the **Instagram** section, connect your Instagram Business account.
3. Enable **Assisted Selling** to allow product search and cart management via Instagram DMs.
4. Enable **Discount Support** to let the bot auto-apply runtime coupons.
5. Save settings.

### Configuring Returns & Exchanges
1. Navigate to **MSG91 > Chat Bot**.
2. Switch to the **Returns & Exchanges** tab.
3. Enable the **Returns & Exchanges** toggle.
4. Save settings.
5. Customers can now initiate returns via Bot by messaging the bot.

### 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**.

### Configuring Stock Alerts
1. Navigate to **MSG91 > Stock Alerts**.
2. Enable the **Stock Alerts** toggle.
3. Select the **WhatsApp Number** to send back-in-stock alerts.
4. Save settings.
5. Customers who previously viewed out-of-stock products will automatically receive a WhatsApp alert when inventory is replenished.

## 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)

## Returns & Exchanges
Allow customers to initiate a return directly through the Bot. The bot validates the order, checks eligibility, and processes the return by creating store credit automatically. Administrators can configure return settings from the admin panel.

- **Return Validation** — Check order status and return window eligibility automatically.
- **Store Credit** — Create store credit for returned items, which customers can use for future purchases.
- **Admin Oversight** — Review and manage all return requests from the WooCommerce admin.

## 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).