=== Vibrate SMS ===
Contributors: lightup
Tags: sms, woocommerce, order notifications, israel, text message
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

SMS for businesses in Israel, from WordPress and WooCommerce through Vibrate: order updates for customers, alerts for your team, manual messages and delivery tracking. Israeli phone numbers only.

== Description ==

Vibrate SMS connects your WordPress site to [Vibrate](https://www.vibrate.co.il), the Israeli SMS and WhatsApp Business platform, with direct connections to every Israeli carrier. One SMS is up to 256 characters in Hebrew, Arabic or English alike.

**For businesses in Israel.** Vibrate delivers SMS to Israeli phone numbers only. Numbers from other countries are never sent and are listed in the SMS log as not sent.

**WooCommerce**

* An SMS to the customer for every order status you choose (processing, completed, on hold, cancelled, refunded, failed, pending payment and custom statuses), each with its own message.
* Placeholders such as {first_name}, {order_number}, {order_total}, {items}, {payment_url}, {order_url} and {tracking_number}.
* Alerts to the shop team's phones when an order is placed or changes status.
* An SMS for every "Note to customer" you add to an order (optional).
* Send an SMS to the customer straight from the order screen, with the order's SMS history next to it.
* A private order note for every SMS sent, refused or blocked.
* Compatible with HPOS (custom order tables) and the block checkout.

**Everywhere else**

* A Send SMS page in wp-admin for one or many numbers.
* An SMS log with delivery status (accepted, sent, delivered, failed), refreshed automatically from Vibrate.
* `vibrate_sms_send()` and `do_action( 'vibrate_sms_send', ... )` for developers, plus filters and actions for every step.

**Built with care**

* The access key is encrypted at rest with your site's own salts, never printed back into the page, and can live in wp-config.php instead.
* Every send carries an Idempotency-Key, so a retry after a timeout can never deliver or bill the same SMS twice.
* Order SMS are sent in the background (Action Scheduler), so checkouts never wait for the SMS API, and they are retried automatically when Vibrate cannot be reached.
* Protection against SMS pumping: SMS go to Israeli numbers only, with hourly limits per number and per site, and names typed by customers are stripped of links before they reach an SMS.
* Each order status is texted at most once per order.
* Works with WordPress privacy tools (export and erase personal data), with a configurable log retention period.
* Hebrew and Arabic translations included. Right-to-left screens are fully supported.

You need a Vibrate account with SMS credits, an access key and an approved sender. [Open an account](https://www.vibrate.co.il/signup).

== Installation ==

1. Download vibrate-sms.zip from https://www.vibrate.co.il/downloads/vibrate-sms.zip.
2. In WordPress go to Plugins > Add New > Upload Plugin, choose the zip and click Install Now, then Activate.
3. In Vibrate, create an access key under Developers > API Keys and make sure your sender is approved under SMS > Sender IDs.
4. In WordPress go to Vibrate SMS > Settings, paste the access key, enter the sender exactly as it appears in Vibrate, and click Save.
5. Click Test connection, then send yourself a test SMS.
6. With WooCommerce, choose which order statuses send an SMS under Vibrate SMS > Settings > WooCommerce.

Updates appear in Dashboard > Updates like any other plugin.

== Frequently Asked Questions ==

= Where do I get an access key? =

In the Vibrate app, under Developers > API Keys (https://www.vibrate.co.il/sms/tokens).

= Why does it say my sender is invalid? =

The sender in the plugin must exactly match an approved, active sender on your Vibrate account (SMS > Sender IDs). Keys of a sub-account can only use senders assigned to that sub-account.

= How much does an SMS cost? =

Every 256 characters of a message count as one SMS per recipient, in any language. The plugin shows the count as you type. Credits are bought in the Vibrate app and never expire.

= A customer did not get an SMS. Why? =

Open Vibrate SMS > Log. Every SMS is listed with its status and, for anything not sent, the reason: an invalid number, a number outside the allowed countries, an hourly limit, or the reason Vibrate gave.

= Can I send to numbers outside Israel? =

No. Vibrate delivers SMS to Israeli phone numbers only. A number from another country is never sent, so it is never charged; the SMS log lists it as not sent, with the reason.

= Can I keep the access key out of the database? =

Yes. Add `define( 'VIBRATE_SMS_ACCESS_TOKEN', 'your-key' );` (and optionally `define( 'VIBRATE_SMS_SENDER', 'MyShop' );`) to wp-config.php.

= Does it send marketing campaigns? =

The plugin is built for transactional messages (order updates, alerts, codes). For campaigns to contact lists, use the Vibrate app. Promotional SMS require the recipient's consent.

== Developers ==

`$result = vibrate_sms_send( '050-1234567', 'Your table is ready.' );`

Returns an array (status, batch_key, run_id, recipients, blocked, units) or a WP_Error. Pass `array( 'async' => true )` to queue it in the background and `array( 'source' => 'my_plugin' )` to label it in the log.

Filters: vibrate_sms_pre_send, vibrate_sms_send_order_sms, vibrate_sms_order_message, vibrate_sms_order_placeholders, vibrate_sms_order_phone, vibrate_sms_send_async, vibrate_sms_rate_limit_exempt_sources, vibrate_sms_send_capability, vibrate_sms_settings_capability.

Actions: vibrate_sms_send, vibrate_sms_sent, vibrate_sms_failed.

API reference: https://www.vibrate.co.il/developers

== Privacy ==

To deliver a message, the plugin sends the recipient's phone number and the message text to the Vibrate API (api.vibrate.co.il), operated by Lightup Software Engineering. It also checks https://www.vibrate.co.il/downloads/vibrate-sms.json for plugin updates; that request carries no personal data. The SMS log stays in your WordPress database and is deleted after the retention period you choose (90 days by default).

== Changelog ==

= 1.2.1 =
* Fixed the text shown in the SMS log for a message the carrier reports as not delivered: it no longer says the credit is refunded, which is not the case.

= 1.2.0 =
* Israel only, said plainly: the plugin sends to Israeli phone numbers only, and says so on the settings and Send SMS pages and in this readme.
* The options to allow other countries and the default country code setting were removed. Team alert numbers must be Israeli too.

= 1.1.0 =
* New design in the Vibrate look: the Vibrate menu icon, a page header with your SMS balance, and a phone preview that shows each message as the recipient will see it, with order templates filled in from a sample order.
* Guided first-time setup in three steps.
* Israeli numbers that cannot exist (not 8 or 9 digits after 972) are refused before anything is sent.

= 1.0.0 =
* First release: WooCommerce order SMS, team alerts, notes to the customer, SMS from the order screen, Send SMS page, SMS log with delivery status, developer API, abuse protection, encrypted access key, Hebrew and Arabic translations.
