=== ForthFocus SMS – OTP Verification, Order Notifications & Indian DLT for WooCommerce ===
Contributors: forthfocus, vgnavada
Tags: woocommerce, sms, otp, dlt, transactional-sms
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Indian DLT-compliant SMS for WooCommerce: order-status notifications, OTP at login / signup / checkout, full delivery logs.

== Description ==

ForthFocus SMS is built for Indian WooCommerce stores that need DLT-ready transactional SMS, order notifications, OTP verification, and operational visibility in one place. It sends order-status notifications to customers and adds phone-number OTP verification to important store touchpoints such as login, registration, cart, and checkout.

It is built for production: instant order-status sends with optional async queue, a custom log table with filtering, search, retry and CSV export, per-template DLT enforcement, real rate-limiting on OTP requests and verifications, segment-aware authoring with live variable-syntax linting, HTTP diagnostics for gateway communication, and a 3-step setup wizard so first-time configuration takes minutes instead of hours.

The plugin currently dispatches via SMSGatewayHub. Additional providers (MSG91, Gupshup, Twilio, Kaleyra) are on the roadmap. The architecture is provider-agnostic — the same templates, OTP flows, and logging continue to work as new providers are added.

= What makes it different =

Most SMS plugins focus only on sending a message or adding a basic OTP form. ForthFocus SMS is focused on the Indian WooCommerce + DLT workflow: every enabled template needs its own DLT Template ID, template syntax is checked before sending, customer OTP flows are rate-limited, gateway responses are logged, balance checks are available inside WordPress, and Diagnostics shows the actual WordPress HTTP request lifecycle for SMSGatewayHub communication.

= What it sends =

* **Order Processing** — when an order moves to Processing
* **Order Completed** — when an order is marked Completed
* **Order Cancelled** — when an order is cancelled
* **Order Refunded** — when a refund is issued
* **OTP for login** — alongside the standard email/password login
* **OTP for registration** — verify the phone number before account creation
* **OTP at checkout** — verify the phone before the customer hits "Place Order" (cuts down on fake / COD fraud orders)

= Why DLT compliance matters =

In India, every commercial SMS must use a sender ID and template registered on the DLT (Distributed Ledger Technology) portal of your telecom operator. Sending unregistered content gets rejected at the operator side, often silently. This plugin enforces DLT correctness at every layer:

* Each template requires its own DLT template ID before it can be enabled.
* The plugin refuses to send any template that has no DLT ID — and logs the attempt so you can see what was skipped and why.
* A live syntax linter catches the most common authoring mistakes (`{order_id)` instead of `{order_id}`, `{#var#}` placeholders pasted verbatim from the DLT portal) before they cause silent rejections.

= Privacy =

* The plugin sends data to the configured SMS gateway (currently SMSGatewayHub) only when an SMS-related action is performed, such as sending an order notification, sending an OTP, testing a template, or refreshing the SMS balance.
* For SMS sending, the data sent to SMSGatewayHub may include the recipient phone number, rendered SMS message body, sender ID, route, channel, Entity ID, DLT Template ID, and the site owner's SMSGatewayHub API key.
* For balance checks, the plugin sends the site owner's SMSGatewayHub API key to the SMSGatewayHub balance endpoint.
* All assets (fonts, scripts, styles) are loaded locally from the plugin folder. The plugin does NOT load anything from external CDNs or third-party servers on either admin or customer-facing pages.
* The plugin does NOT send usage analytics, telemetry, tracking events, or call-home data to ForthFocus.
* OTP codes are hashed (with a per-phone salt) before storage. Plaintext OTP codes are redacted from log entries.
* Store owners are responsible for ensuring that their SMS use complies with applicable consent, privacy, telecom, DLT, and customer communication rules.

== External services ==

This plugin connects to SMSGatewayHub, a third-party SMS gateway service, to send transactional SMS messages and fetch SMS balance information. An SMSGatewayHub account, API key, approved sender ID/Header, Entity ID, and approved DLT templates are required for live SMS delivery.

The plugin connects to the following SMSGatewayHub endpoints:

* `https://www.smsgatewayhub.com/api/mt/SendSMS` — used when the site owner sends an SMS, such as an order-status notification, OTP message, or template test. The plugin sends the recipient phone number, rendered message body, sender ID, route, channel, Entity ID, DLT Template ID, and the site's SMSGatewayHub API key.
* `https://www.smsgatewayhub.com/api/mt/GetBalance` — used when the dashboard or gateway settings page fetches the SMS balance. The plugin sends the site's SMSGatewayHub API key.

SMS content and phone numbers are sent to SMSGatewayHub only when the site owner enables the plugin and performs an SMS-related action or when a configured WooCommerce/OTP event triggers an SMS.

Service provider: SMSGatewayHub
Terms and Conditions: https://www.smsgatewayhub.com/terms-and-conditions
Privacy Policy: https://www.smsgatewayhub.com/privacy-policy
API Documentation: https://www.smsgatewayhub.com/free-sms-gateway-developer-api

= Compatibility =

The plugin works on both classic (shortcode-based) and block-based WooCommerce checkout, but the depth of integration differs:

* **Classic checkout** (`[woocommerce_checkout]` shortcode, used by Storefront, Astra, GeneratePress, Flatsome, URNA, Dokan-style themes, and any site with the WC checkout shortcode) — full integration. The OTP gate renders above the checkout form, the billing phone field is automatically locked to the verified number once verification is complete, and the user uses a "Change phone" link if they need to switch numbers.
* **Block-based checkout** (the new WC Checkout Block, used by Twenty Twenty-Five and other FSE themes by default) — basic integration. The OTP gate renders above the checkout block. The billing phone field inside the React-managed block cannot be locked from outside the block API, so the user is technically able to edit it after verifying. However, the server-side Store API guard rejects order placement if the submitted phone does not match the verified number — so the verification is still enforced, just at submission rather than at the field level. Tightening this into a native checkout-block extension is on the v1.1 roadmap.

For the strictest UX and behavior (auto-locked phone field, no possibility of submitting a mismatched number), use the classic checkout. To switch from block-based to classic on a Twenty Twenty-Five site, edit the Checkout page and replace the "Checkout" block with the `[woocommerce_checkout]` shortcode.

= Setup wizard =

A 3-step setup wizard guides you through:

1. Gateway credentials (API key, sender ID, route, channel, entity ID)
2. Notification templates (DLT ID + approved message body for each order event you want to notify on)
3. OTP verification (which flows to enable, and the OTP message templates)

You can re-run the wizard from the Dashboard at any time, or skip it entirely if you prefer to configure manually.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install it through the WordPress Plugins screen.
2. Activate the plugin.
3. Go to **ForthFocus SMS → Dashboard** in the WordPress admin.
4. Click **Run Setup Wizard** and follow the 3-step flow.

== Frequently Asked Questions ==

= Does this work without WooCommerce? =

The plugin requires WooCommerce. The OTP module also works on the standard WordPress login (wp-login.php) regardless.

= What gateways are supported? =

The plugin currently dispatches via SMSGatewayHub. Adapters for MSG91, Gupshup, Twilio, and Kaleyra are planned for upcoming releases. The plugin's architecture is provider-agnostic — once a new adapter is added, the same templates and OTP flows continue to work.

= Will this work with my existing SMS provider? =

Right now the plugin sends through SMSGatewayHub. If you have an account with a different provider (MSG91, Gupshup, Twilio, etc.), you have three options: (1) sign up for an SMSGatewayHub account, (2) wait for the planned multi-provider release, or (3) hook into our `ffsms_before_send` filter and dispatch to your own provider in custom code while still benefiting from our DLT enforcement, logging, and OTP machinery.

= I am getting error 0024 when sending — what does it mean? =

0024 means your message body does not match the DLT-approved template registered with your operator. The most common causes are: extra text outside what was registered, wrong punctuation, malformed variable syntax (use `{curly_braces}` not `{round_braces}` or `{#var#}`), or emojis that the operator does not accept. The plugin's live linter catches most of these as you type.

= Does this support OTP only for COD orders? =

Per-payment-method OTP gating is planned for the next release. In the current version, OTP at the cart page applies to all payment methods. You can also wire it via custom code using the `ffsms_before_send` filter.

= How does the plugin handle DND (Do Not Disturb) numbers? =

DND handling is enforced at the operator side, not in the plugin. If you send to a DND-registered number using a template approved under the "Promotional" or "Explicit" category, the operator returns code 640-659 and the plugin marks the send as failed with the operator's reason. To deliver to DND numbers, get your template approved under the "Service" or "Implicit" category on the DLT portal.

= Can I send promotional SMS / campaigns / cart abandonment? =

Not in the free version. Those features are planned for the upcoming Pro tier.

= Where are OTP codes stored? =

OTP codes are stored in a dedicated `wp_ffsms_otp` database table, hashed with a per-phone salt and a per-site secret. Plaintext OTP values never persist. Codes have a configurable expiry (default 10 minutes) and a resend cooldown (default 30 seconds). The plugin enforces a max-attempts lockout to prevent brute-forcing.

= Will this work with international phone numbers? =

Phone numbers are normalized to E.164-style digits (country code + national number, no `+`). The default country code is configurable in Gateway settings. If your DLT registration covers Indian numbers only, sends to non-Indian numbers may be rejected by the operator — that is a DLT/operator policy, not a plugin restriction.

= Does the plugin work with the new WooCommerce Checkout Block? =

Partially, with a documented limitation. The OTP verification gate renders above the Checkout Block on Twenty Twenty-Five and other FSE themes that use it, and the server-side guard rejects orders where the submitted phone does not match the verified number. However, because the Checkout Block's phone input is managed by React inside the block, it cannot be auto-locked from outside the block API — the user can technically type a different number after verifying. Verification is still enforced (at order submission), but the experience is tighter on the classic shortcode-based checkout where the phone field can be locked at the field level. Native checkout-block integration is on the v1.1 roadmap. For the strictest behavior in the meantime, use the classic checkout shortcode.



The plugin declares compatibility with WooCommerce's High-Performance Order Storage (HPOS) and the Cart/Checkout Block APIs. All order-related operations use the HPOS-safe `WC_Order` API rather than legacy postmeta queries.

= How do I extend the plugin? =

Three filters and one action are exposed:

* `apply_filters('ffsms_render_message', $message, $template_id, $vars, $opts)` — modify the rendered body before send
* `apply_filters('ffsms_before_send', $params)` — modify dispatch parameters (phone, message, dlt_template_id) just before the gateway call. Returning empty cancels the send.
* `do_action('ffsms_after_send', $result, $phone, $message, $template_id)` — observer hook fired after the gateway responds
* `do_action('ffsms_dispatch_sms', $phone, $template_id, $vars)` — programmatic send: routes through Sender::send_template with full DLT enforcement, logging, and dedupe. Note: this hook is intentionally named `ffsms_dispatch_sms` (not `ffsms_send_sms`) to avoid colliding with the plugin's internal Action Scheduler queue hook.

= How do I report a security vulnerability? =

Please email security details to support@forthfocus.com (or open a private message via forthfocus.com) instead of posting to the public .org support forum or opening a public GitHub issue. We aim to acknowledge reports within 2 business days and ship a coordinated fix before any public disclosure. Include a clear reproduction, plugin version, WordPress version, WooCommerce version, and any logs that demonstrate the issue.

= Is this plugin DLT compliant? =

Yes. India's Telecom Regulatory Authority (TRAI) requires all commercial SMS to be sent under DLT (Distributed Ledger Technology) registration, with a registered Header (sender ID), an approved Entity ID, and an approved DLT Template ID for every message body. The plugin enforces this end-to-end: every template requires a DLT Template ID before it can be enabled, the placeholder syntax is validated against DLT-style variable rules, and the gateway request always includes the EntityId + dlttemplateid + sender ID parameters. Templates without a DLT ID are blocked from sending.

= Can I use this for COD (Cash on Delivery) order verification? =

Yes — the cart-page and checkout-page OTP gates are designed exactly for this. Verifying the customer's phone number before "Place Order" cuts down on fake / abandoned COD orders that would otherwise generate failed deliveries and return-shipping costs. Per-payment-method gating (e.g. require OTP only for COD orders, skip for prepaid) is on the roadmap.

= What is the difference between transactional and promotional SMS in India? =

Transactional SMS (channel 2 in our gateway settings) is for order confirmations, OTPs, delivery updates, and other essential service messages. It is delivered 24/7 even to DND-registered numbers. Promotional SMS (channel 1) is for marketing campaigns and offers — it is restricted to 9am–9pm and is blocked for DND numbers. The plugin defaults to transactional channel for all order and OTP templates because that is the appropriate category for the messages it sends. Make sure your DLT template registration matches the channel you select.

= Can I use my existing SMSGatewayHub account? =

Yes. Paste your SMSGatewayHub API key, sender ID, Entity ID, and the DLT Template IDs you've already registered into the plugin's setup wizard. There's nothing to migrate — the plugin works on top of your existing account and SMS credit balance. The Dashboard shows your live SMS balance via the gateway's GetBalance API.

= How much does SMS cost in India? =

SMS is billed per segment, not per message. Indian transactional SMS pricing typically ranges from ₹0.10 to ₹0.30 per segment depending on your gateway provider and volume tier. A "segment" is 160 characters for plain English (GSM-7 encoding) or 70 characters for Unicode (Kannada, Hindi, Marathi, Tamil, etc.). Multi-segment messages count as multiple sends. The plugin shows a live segment counter in the template editor so you can see exactly how many segments each message will use before sending. Long DLT-registered templates with personalization variables can easily span 2–3 segments — worth checking before bulk sends.



1. Dashboard with live SMS balance, status checklist, and quick actions
2. Gateway settings — credentials, master switches, and a "test an approved template" panel
3. Notification templates page — DLT-required template management with live segment counter and variable linter
4. OTP configuration — module switches and per-flow OTP message templates
5. Logs page — filterable, searchable, with detail modal and CSV export
6. Setup wizard — 3-step flow for first-time configuration

== Screenshots ==

1. Dashboard with live SMS balance, status checklist, and quick actions
2. Gateway settings — credentials, master switches, and a "test an approved template" panel
3. Notification templates page — DLT-required template management with live segment counter and variable linter
4. OTP configuration — module switches and per-flow OTP message templates
5. Logs page — filterable, searchable, with detail modal and CSV export
6. Setup wizard — 3-step flow for first-time configuration

== Changelog ==

= 1.0.0 =
* First public release.

== Upgrade Notice ==

= 1.0.0 =
First public release.

== Trademark Notice ==

ForthFocus is a trademark of FORTHFOCUS GROUP.

WordPress, WooCommerce, and Woo are trademarks of their respective owners. This plugin is not affiliated with, endorsed by, sponsored by, or officially associated with the WordPress Foundation, Automattic Inc., WooCommerce, or Woo.

SMSGatewayHub, MSG91, Gupshup, Twilio, and Kaleyra are trademarks or brands of their respective owners. This plugin currently integrates with SMSGatewayHub as a third-party SMS service provider; MSG91, Gupshup, Twilio, and Kaleyra are referenced only as examples of additional providers planned for future releases. The plugin is not officially endorsed by or affiliated with any of these companies unless stated through a formal partnership.
