=== TopSMS - SMS for WooCommerce ===
Contributors: topsmscz
Tags: sms, woocommerce, order notifications, sms notifications, sms gateway
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send SMS to customers when their WooCommerce order changes status and get an SMS about every new order, through the TopSMS.cz gateway.

== Description ==

TopSMS - SMS for WooCommerce connects your shop to the [TopSMS.cz](https://www.topsms.cz) SMS gateway, a Czech B2B SMS service with delivery to all Czech and Slovak mobile networks and international destinations.

**What it does**

* Sends an SMS to the customer's billing phone number when the order changes to a status you enable (processing, completed, on hold, cancelled, refunded, failed, pending, or any custom status).
* Optionally sends an SMS to the shop owner about every new order placed at checkout.
* Message templates per status with placeholders: `{order_number}`, `{first_name}`, `{last_name}`, `{total}`, `{status}`, `{payment_method}`, `{shipping_method}`, `{order_date}`, `{shop_name}`, `{site_url}`.
* Custom Sender ID (the name the customer sees as the sender), once approved for your TopSMS account.
* Phone numbers are normalised to international format using the billing country, so numbers such as `608 123 456` or `0905 123 456` are handled.
* Sending runs in the background through Action Scheduler, so the checkout never waits for the gateway.
* Every attempt is written to the order notes and to a log screen (WooCommerce > SMS log). The log is pruned after a configurable number of days.
* Connection check and test SMS button in the settings.
* Compatible with High-Performance Order Storage (HPOS) and both the classic and the block checkout.

**Requirements**

* WooCommerce 8.0 or newer.
* A TopSMS.cz account and an API key (created in the TopSMS dashboard, section API). Registration is free; messages are charged to the credit of your TopSMS account according to the [TopSMS price list](https://www.topsms.cz/cenik).

**Third-party service**

This plugin relies on the TopSMS.cz SMS gateway, a paid third-party service operated by TopSMS.cz (Vojtech Safar, Prague, Czech Republic). Messages are sent through the TopSMS REST API at `https://www.topsms.cz/api`. For every message the plugin transmits the recipient phone number, the message text (which may contain the customer name and order details depending on your templates), the Sender ID and your shop URL (in the User-Agent header). The connection check transmits only your API key. No data is sent unless you enter an API key.

* Terms of service: [https://www.topsms.cz/obchodni-podminky](https://www.topsms.cz/obchodni-podminky)
* Privacy policy: [https://www.topsms.cz/zasady-ochrany-osobnich-udaju](https://www.topsms.cz/zasady-ochrany-osobnich-udaju)
* Data processing agreement (GDPR): [https://www.topsms.cz/zpracovatelska-smlouva](https://www.topsms.cz/zpracovatelska-smlouva)
* API documentation: [https://www.topsms.cz/api-integrace/rest-api](https://www.topsms.cz/api-integrace/rest-api)

**Developer hooks**

* `topsms_wc_recipient_phone` (filter): change the recipient number, receives `$phone, $order, $status`.
* `topsms_wc_message_text` (filter): change the final text, receives `$text, $order, $status`.
* `topsms_wc_should_send` (filter): return `false` to skip a notification, receives `true, $order, $status`.
* `topsms_wc_sms_sent` (action): fires after every attempt with `$order, $phone, $text, $result`.

== Installation ==

1. Install and activate the plugin (WooCommerce must be active).
2. Register at [www.topsms.cz](https://www.topsms.cz) and create an API key in the dashboard, section API.
3. Go to WooCommerce > Settings > TopSMS, paste the API key and click "Check connection".
4. Enable the order statuses that should trigger an SMS and adjust the templates.
5. Optionally enable the shop owner notification and enter your phone number.
6. Send a test SMS to your own number to confirm everything works.

== Frequently Asked Questions ==

= Which countries can I send to? =

TopSMS delivers to all Czech and Slovak mobile networks and to international destinations. Prices per destination are listed at https://www.topsms.cz/cenik.

= How is a message priced? =

Each SMS part is charged to your TopSMS credit. Plain ASCII messages carry 160 characters per part; messages with characters outside the GSM alphabet (Czech diacritics, emoji) carry 70 characters per part. The settings screen explains this next to the templates.

= Can I use my own sender name? =

Yes. Request a Sender ID in your TopSMS dashboard. Mobile operators approve new sender names in batches, usually a few times per month, so allow one to two weeks. Until it is approved, leave the field empty and the default TopSMS sender is used.

= Does the customer receive the same status twice? =

No. Each status is announced once per order, even if the order goes back and forth between statuses.

= The SMS was not sent. Where do I look? =

Open the order: the plugin leaves an order note for every attempt, including the gateway error message. WooCommerce > SMS log lists the last 100 messages. WooCommerce > Status > Logs (source "topsms") contains failures as well.

= Does it work with HPOS and the block checkout? =

Yes, both are supported.

== Changelog ==

= 1.0.0 =
* Initial release: customer status notifications, shop owner new-order SMS, templates with placeholders, Sender ID, phone normalisation, background sending, log screen, test button, Czech translation.
