=== Besked Notifications ===
Contributors: giangel84
Tags: notifications, woocommerce, sms, messaging, whatsapp
Requires at least: 6.2
Tested up to: 6.9
Stable tag: 1.5.4
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send WhatsApp notifications via Besked API. Native WooCommerce integration for order notifications, contact management, and broadcast campaigns.

== Description ==

Besked WhatsApp Notifications connects your WordPress site to the Besked WhatsApp messaging platform, enabling you to:

* Send automated WhatsApp notifications for WooCommerce orders (new order, processing, completed, cancelled, refunded, on-hold, and custom statuses)
* Manage a contact address book with WhatsApp consent (GDPR-compliant)
* Create and schedule broadcast campaigns to contact lists with per-recipient personalisation
* Track abandoned carts and send automated recovery messages
* Import contacts from WooCommerce orders, WordPress users, or CSV files
* Collect WhatsApp consent at checkout, on the account page, and via a dedicated "My Account" section

= Key Features =

**Order Notifications**
Automatically notify customers on every order status change with fully customisable message templates and dynamic placeholders (`{order_number}`, `{order_total}`, `{customer_first_name}`, etc.).

**Contact Management**
Full-featured address book with search, filtering, list segmentation, CSV import/export, and bulk actions (enable/revoke consent, add/remove from lists).

**Broadcast Campaigns**
Compose WhatsApp campaigns with a live preview editor (bold, italic, strikethrough, monospace), attach images or documents, schedule delivery, and track per-contact delivery logs.

**Abandoned Cart Recovery**
Detect abandoned carts and automatically send recovery messages after a configurable delay, with optional discount coupon codes.

**GDPR & Consent**
Collect explicit WhatsApp consent at checkout and in the account area. Contacts can unsubscribe via a secure tokenised link in any message.

= Requirements =

* A Besked account and API key — sign up at [besked.it](https://besked.it)
* WordPress 6.2 or higher
* PHP 7.4 or higher
* WooCommerce 5.0+ (optional — required only for order notifications and cart tracking)

== Installation ==

1. Upload the `besked-wa-notifications` folder to the `/wp-content/plugins/` directory, or install directly from the WordPress plugin directory.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **Besked → Impostazioni** and enter your API Key and Session ID from your [Besked dashboard](https://app.besked.it).
4. Configure notification templates under **Notifiche WooCommerce**.
5. (Optional) Enable WhatsApp consent collection under **GDPR & Consenso**.

== Frequently Asked Questions ==

= Do I need a Besked account? =

Yes. The plugin sends messages through the Besked API. You need a Besked account and an active WhatsApp session. Sign up at [besked.it](https://besked.it).

= Does it work without WooCommerce? =

Yes. The contact address book, campaign management, and manual messaging features work independently of WooCommerce. Order notification and cart abandonment features require WooCommerce.

= Is it GDPR compliant? =

The plugin includes a built-in consent system. You can collect explicit opt-in at checkout and in the customer account area. Contacts can unsubscribe at any time via a secure link. No message is sent to contacts without `whatsapp_consent = 1`.

= What placeholders are available in message templates? =

Order templates: `{order_number}`, `{order_date}`, `{order_total}`, `{order_status}`, `{customer_first_name}`, `{customer_last_name}`, `{customer_email}`, `{billing_address}`, `{shipping_address}`, `{payment_method}`, `{order_items}`, `{site_name}`, `{site_url}`, `{customer_note}`, `{bacs_details}`, `{unsubscribe}`.

Campaign templates: `{first_name}`, `{last_name}`, `{phone}`, `{email}`, `{site_name}`, `{site_url}`, `{unsubscribe}`.

= Can I send to contacts without WooCommerce? =

Yes. Import contacts via CSV or from existing WordPress users (with custom phone field mapping via **Impostazioni → Mappa campi custom**), then create a campaign or send manual messages.

== Screenshots ==

1. Settings page — API configuration and session management
2. Contact address book with search, filters, and bulk actions
3. Campaign editor with live WhatsApp preview
4. WooCommerce order notification templates
5. Abandoned cart automation rules

== External services ==

This plugin connects to the Besked WhatsApp messaging API (provided by Besked.it, https://besked.it) to deliver WhatsApp messages and to manage WhatsApp sessions. Using the plugin therefore requires an active Besked account and an API key, which the site owner enters in the plugin settings.

**What the service is and what it is used for**

Besked is a third-party WhatsApp messaging gateway. The plugin relies on it to:

* Send single WhatsApp messages (for example, WooCommerce order status notifications).
* Send bulk/broadcast WhatsApp campaigns to contact lists, with optional media attachments.
* Retrieve the list of WhatsApp sessions available for the account.
* Check the connection status of a WhatsApp session.

**What data is sent, and when**

The following requests are made to `https://app.besked.it`:

* `POST /api/v1/send` — every time a single WhatsApp notification is sent (for example, when a WooCommerce order changes status, or an abandoned cart recovery message is triggered). Data sent: the configured Session ID, the recipient phone number in E.164 format, the message body, and optionally a media URL, media type and file name.
* `POST /api/v1/send/bulk` — every time a campaign is dispatched. Data sent: the Session ID, the message template and the recipient list (phone number plus any per-recipient personalisation variables), and optional media.
* `GET /api/v1/sessions` — when the site administrator opens the plugin settings page, to display the list of available WhatsApp sessions.
* `GET /api/v1/sessions/{session_id}/status` — when the site administrator checks the connection status of a session.

Every request includes the API key configured by the site owner, sent as the `X-API-Key` HTTP header for authentication. No data is sent to Besked for visitors who have not given WhatsApp consent (consent is stored per contact as `whatsapp_consent = 1`).

**Service provider, terms and privacy**

The service is provided by Besked.it. For details about how Besked handles the data it receives, please refer to the provider's legal documents:

* Terms of Service: https://besked.it/termini.html
* Privacy Policy: https://besked.it/privacy-policy.html

== Changelog ==

= 1.5.4 =
* Code quality: in `ajax_media_upload()` removed the unused `require_once wp-admin/includes/media.php` and moved `require_once wp-admin/includes/image.php` immediately before `wp_generate_attachment_metadata()`, so each core admin file is loaded right before the function from it is used
* Security: added an explicit `wp_verify_nonce( 'woocommerce-process_checkout' )` check at the start of `validate_phone()`, `sanitize_phone_on_save()` and `save_checkout_data()` in the WooCommerce checkout integration, so the nonce verification is visible inline (it was already enforced upstream by WooCommerce)
* Security: added a `besked_media_filters` nonce to the Besked Media admin page sort/filter links and form, with `wp_verify_nonce` on incoming requests; filter and sort query args are now ignored unless accompanied by a valid nonce

= 1.5.3 =
* Code quality: replaced all inline `<script>` and `<style>` tags with `wp_enqueue_script()`, `wp_enqueue_style()`, `wp_add_inline_script()`, and `wp_localize_script()` per WordPress coding standards
* Security: added nonce verification to the checkout cart-tracking AJAX endpoint (`besked_track_billing`)
* Security: input fields of the abandoned-cart automation save handler are now individually sanitised with the appropriate WordPress functions (`sanitize_text_field`, `wp_kses_post`, `absint`, whitelist checks)
* Security: replaced direct SQL interpolation with `$wpdb->prepare()` and placeholders across campaigns, messages, contacts, abandoned-carts and lists queries
* Docs: added the `== External services ==` section describing the Besked API usage, data sent and links to the provider's Terms of Service and Privacy Policy

= 1.4.0 =
* Added "Import from WordPress users" feature with phone field mapping
* Added "Custom field mapping" settings tab for non-WooCommerce phone fields
* Added media attachments (image/document) to broadcast campaigns
* Added Besked Media library page with bulk delete
* Added CSV import with auto-detected delimiter and column mapping
* Improved bulk action confirmation prompts

= 1.3.0 =
* Added broadcast campaigns with per-recipient variable substitution
* Added live WhatsApp preview editor with formatting toolbar
* Added campaign scheduling and per-contact delivery logs

= 1.2.0 =
* Added contact list segmentation
* Added GDPR unsubscribe tokens
* Added My Account "Notification preferences" endpoint

= 1.1.0 =
* Added abandoned cart tracking and automated recovery messages
* Added Formidable Forms integration

= 1.0.0 =
* Initial release

== Upgrade Notice ==

= 1.4.0 =
New: WordPress user import, custom phone field mapping, media attachments for campaigns.
