=== 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 WhatsApp, allowing customers to initiate returns, exchanges, and refunds directly through the bot. Administrators can configure return windows, refund methods, and exchange policies 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 policies, 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, exchanges, and refunds via Bot with automated order validation and refund processing.
- **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`)

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

== 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.

== COD to Prepaid ==

== 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:

= 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 the WooCommerce Support Forums.

== Frequently Asked Questions ==
= What is MSG91? =
MSG91 is a cloud communication platform that provides SMS, WhatsApp, and chat-bot services for businesses.

= Do I need a MSG91 account? =
Yes, you need a MSG91 account to obtain the AuthKey and bot IDs required for SMS and chat-bot features.

= Is this plugin free? =
Yes, this plugin is free and open source under the GPLv2 license.

= Does this plugin work with WooCommerce? =
Yes, WooCommerce must be installed and activated.

= Can customers checkout from WhatsApp? =
Yes. The plugin generates a tokenized checkout URL that restores the bot cart and session in the browser.

= What customer types are supported? =
Guest (widget), mobile (WhatsApp), and logged-in WordPress users. Each has a deterministic session and isolated cart.

= Can I convert COD orders to prepaid? =
Yes. The plugin can send automated WhatsApp messages to COD customers offering a discount to switch to prepaid. You can choose how the original order is updated (tag, cancel + recreate, or mark as paid) and review conversion logs in the admin panel.

== Screenshots ==
1. MSG91 Settings — Authentication Configuration (AuthKey, Country, IP, Domain)
2. MSG91 Chat Widget — Widget Token and WhatsApp Configuration
3. MSG91 Chat Bot — Bot Instructions, Assisted Selling, Discount Support, and WhatsApp Settings
4. MSG91 Automations — Campaign and notification automation management interface
5. MSG91 COD to Prepaid — Configuration, order types, and discount rules
6. MSG91 COD to Prepaid Logs — Conversion tracking and activity logs

== Changelog ==
= 3.0.0 =
* Added Returns & Exchanges — customers can initiate returns, exchanges, and refunds via Bot.
* Added Stock Alerts — automatic WhatsApp notifications when out-of-stock products are back in stock.
* Added Facebook Bot integration for conversational commerce via Facebook Messenger.
* Added Instagram Bot integration for conversational commerce via Instagram DMs.

= 2.0.0 =
* Added AI VoiceBot API with natural-language product search, cart CRUD, discount, checkout, and order placement.
* Added WhatsApp Bot integration with assisted selling and discount support.
* Added runtime coupon / discount engine with channel-aware rules.
* Added tokenized checkout for seamless WhatsApp-to-browser hand-off.
* Added fuzzy product search with intent parsing (price, sort, category, brand, tag, attributes, compare, related).
* Added Web Chat Widget integration with WooCommerce customer data sync.
* Updated admin settings panel for unified chat-bot and WhatsApp-bot configuration.

= 2.1.0 =
* Added COD to Prepaid conversion flow with WhatsApp outreach and configurable order-update strategies.
* Added COD to Prepaid Logs for conversion tracking and filtering.

= 1.0.0 =
* Initial release
* Basic SMS automation functionality
* Admin interface for managing automations
* Secure AuthKey storage

== Upgrade Notice ==
= 3.0.0 =
Adds Returns & Exchanges, Stock Alerts, Facebook Bot, and Instagram Bot. Review the new Chat Bot tabs and Stock Alerts settings after updating.

= 2.1.0 =
Adds COD to Prepaid conversion flow with WhatsApp outreach and configurable order-update strategies. Review the new COD to Prepaid settings after updating.

= 2.0.0 =
Major upgrade adding AI chatbot, WhatsApp bot, product search, cart API, and discount engine. Review the new Chat Bot and WhatsApp Bot settings after updating.

= 1.0.0 =
Initial release of the plugin.