=== TellbySMS by ScopeHost ===
Contributors: scopehostdev, siphesihlem
Tags: sms, notifications, woocommerce, otp, 2fa
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send SMS notifications, OTP/2FA, scheduled messages and subscriber broadcasts via TellbySMS — the bulk SMS platform built for Southern Africa.

== Description ==

**TellbySMS** connects your WordPress site to the [TellbySMS](https://sms.scopehost.net) bulk SMS platform, giving you a complete suite of SMS tools right inside your WordPress dashboard.

Whether you want to notify customers about their WooCommerce orders, secure logins with two-factor authentication, grow an SMS subscriber list, or send scheduled marketing messages — TellbySMS has you covered.

---

### 📱 OTP & Two-Factor Authentication (2FA)

Add an extra layer of security to your WordPress login. When enabled, users receive a 6-digit verification code via SMS after entering their password. The code expires in 5 minutes and is invalidated after 5 failed attempts.

* Works on the standard WordPress login page
* Optional `[tellbysms_otp_form]` shortcode for custom login flows
* Resend code link included

---

### 📤 SMS Outbox

Every SMS sent through the plugin is automatically logged in a clean table — so you always know what was sent, to whom, when and why.

* Recipient, message, sender ID, status and trigger type
* Up to 500 recent messages displayed
* Accessible under TellbySMS → Outbox

---

### 📋 SMS Subscribers

Build an SMS mailing list directly on your WordPress site. Visitors opt in using a shortcode or sidebar widget and you can broadcast to all active subscribers with one click.

* `[tellbysms_subscribe]` shortcode — add to any page or post
* Sidebar widget with customisable label and button text
* Welcome SMS sent automatically on new subscription
* Broadcast message to all active subscribers from WP admin
* Optional auto-sync of subscribers to a TellbySMS contact group
* Manage subscribers under TellbySMS → Subscribers

---

### ⏰ Scheduled SMS

Schedule an SMS to go out at exactly the right time — to individual numbers, comma-separated lists or an entire TellbySMS contact group.

* Pick any future date and time using a datetime picker
* WP-Cron processes due messages every minute
* Cancel pending schedules before they fire
* Sent results logged to Outbox automatically
* Manage under TellbySMS → Scheduled SMS

---

### 🔔 Admin Alerts

Stay informed about important site activity without having to check your dashboard.

* **New post published** — receive an SMS whenever a new blog post goes live
* **WordPress/plugin update** — SMS confirmation when an update completes successfully
* **Admin login alert** — security SMS with username and IP address whenever an admin logs in

All alert messages are fully customisable with variables like `{site_name}`, `{post_title}`, `{author}`, `{user_name}` and `{ip}`.

---

### 🛒 WooCommerce Integration

Keep customers informed at every stage of their order journey.

* SMS to customer on new order placement
* SMS to admin on new order (with order total and customer name)
* SMS on order status change — configure a custom message per status (processing, completed, shipped, cancelled, on-hold, refunded)
* Order notes added automatically for every SMS sent
* Personalisation variables: `{customer_name}`, `{order_id}`, `{order_total}`, `{order_status}`, `{site_name}`

---

### 👤 WordPress Notifications

* Welcome SMS to new users on registration
* Password reset notification SMS
* Admin alert when a new user registers (with name and email)

---

### 📊 Dashboard Widget

A quick-glance SMS stats widget on your WordPress dashboard showing your current balance, total SMS sent, scheduled messages and total contacts — with a direct link to Send SMS.

---

### ✉️ Manual SMS

Send a message directly from WordPress admin to one or more phone numbers, a specific WordPress user, all users with a phone number, or an entire TellbySMS contact group. Includes a live SMS character counter.

---

### 🔄 Contact Sync

One-click sync of WordPress users and WooCommerce customers to your TellbySMS contact list — with optional target group assignment and a detailed sync log.

---

### 📌 Shortcodes

* `[tellbysms_balance]` — Display your current credit balance
* `[tellbysms_subscribe]` — SMS subscription opt-in form
* `[tellbysms_otp_form]` — OTP verification form for custom login flows

---

### 🔑 Requirements

* A TellbySMS account at https://sms.scopehost.net
* Your API token from the API Access page

== External Services ==

This plugin connects to the **TellbySMS** bulk SMS service operated by The ScopeHost Operating Company, a division of Cubic Systems Investments (Pty) Ltd.

**What the service is:**
TellbySMS is a bulk SMS platform that enables sending SMS messages through the Connect Mobile gateway network in Southern Africa.

**When data is sent:**
This plugin makes requests to `https://sms.scopehost.net/api/v1` in the following situations:
* When sending an SMS notification (WooCommerce order, admin alert, OTP code, subscriber broadcast, scheduled SMS, or manual send)
* When checking your account credit balance (dashboard widget and Send SMS page)
* When syncing WordPress contacts to TellbySMS contact groups

**What data is sent:**
* Your API token (for authentication on every request)
* Recipient phone numbers
* SMS message content
* Sender ID (if configured)

**No personal data is stored by the plugin** beyond what is already in your WordPress database. All SMS sending and logging is handled server-side by TellbySMS.

* Service website: https://sms.scopehost.net
* Terms of Service: https://sms.scopehost.net/terms
* Privacy Policy: https://sms.scopehost.net/privacy

== Installation ==

1. Upload the `tellbysms` folder to `/wp-content/plugins/`
2. Activate the plugin in WordPress Admin → Plugins
3. Go to TellbySMS → Settings → Connection and enter your API token
4. Click Test Connection to verify
5. Configure notifications, OTP, WooCommerce and subscriber settings as needed

== Frequently Asked Questions ==

= Where do I get my API token? =
Log in to https://sms.scopehost.net and go to API Access.

= Does OTP work for all users? =
OTP works for any user who has a phone number stored in their profile (billing_phone, phone or mobile meta field). Users without a phone number will be able to log in without OTP.

= Does this work without WooCommerce? =
Yes. WooCommerce features are only loaded when WooCommerce is active. All other features work independently.

= How does scheduled SMS work? =
WordPress WP-Cron processes scheduled messages every minute. The message is sent via the TellbySMS API at the scheduled time and the result is logged in your Outbox.

= What phone number format should I use? =
Include the full international number with country code (e.g. 26876123456 for Eswatini). The TellbySMS API normalises numbers automatically.

= How do I display the credit balance on my site? =
Use the shortcode `[tellbysms_balance]` on any page or widget.

== Changelog ==

= 2.0.0 =
* Added OTP / Two-Factor Authentication (2FA) login
* Added SMS Outbox with full send history
* Added SMS Subscribers with shortcode, widget and broadcast
* Added Scheduled SMS with WP-Cron processing
* Added Admin Alerts: new post, WP update, admin login
* Added WordPress Dashboard stats widget
* Settings expanded to 6 tabs

= 1.0.0 =
* Initial release — WooCommerce order SMS, user registration, password reset, manual SMS, contact sync

== Upgrade Notice ==

= 2.0.0 =
Major update — adds OTP/2FA, Outbox, Subscribers, Scheduled SMS and Admin Alerts. Deactivate and re-upload to upgrade.

== Screenshots ==

1. **Send SMS** — Send to individual numbers, WordPress users or entire contact groups with a live character counter.
2. **Settings — Connection** — Enter your API token, base URL and default Sender ID. Test connection with one click.
3. **WooCommerce Integration** — Configure custom SMS messages for every WooCommerce order status.
4. **OTP / 2FA** — Two-factor authentication settings with customisable verification message.
5. **Scheduled SMS** — Schedule messages with date/time picker. Manage and cancel pending sends.
6. **SMS Subscribers** — Broadcast to all SMS subscribers with opt-in shortcode and widget management.
7. **SMS Outbox** — Full log of every SMS sent — recipient, message, status and trigger.
8. **Dashboard Widget** — Quick-glance credit balance, SMS stats and shortcut to Send SMS.
