=== AfroIT Messaging Workflows for WooCommerce ===
Contributors: afroit
Donate link: https://messaging-workflows.com/
Tags: woocommerce, automation, workflow, whatsapp, email
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 8.0
Requires Plugins: woocommerce
WC requires at least: 8.6
WC tested up to: 10.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create automated workflows with triggers, conditions, and actions for WhatsApp, SMS, and email.

== Description ==

**AfroIT Messaging Workflows for WooCommerce** helps merchants automate follow-up communication when customers place orders, pay, abandon carts, or when order status changes. Combine **triggers**, **conditions**, and **actions** (including **Wait**, **Send WhatsApp**, **Send SMS**, and **Send Email**) to build flows that match your store's policies and marketing goals.

Workflows run **on your WordPress site**. Designed specifically for WooCommerce. Compatible with WooCommerce High-Performance Order Storage (HPOS). Not supported on WordPress Multisite.

= What is a workflow? =

A **workflow** is a saved automation rule in your store. Each workflow has four main parts:

1. **Name** — A label you recognize in the admin (e.g. "Post-purchase thank you + upsell").
2. **Trigger** — The WooCommerce event that starts the workflow (for example, *Payment Complete*, *Payment Failed*, *Order Status: Processing*, or *Shopping Cart Abandoned*).
3. **Conditions** (optional) — Rules that must be true for the workflow to run, using order and store **variables** (for example, order total, product list, payment method). If conditions fail, the workflow does not run.
4. **Steps (actions)** — An ordered list of **actions** executed one after another. Some actions can **wait** and resume later.

Workflows are **active** or **inactive**. Only **active** workflows are evaluated when a trigger fires.

Actions run in sequence and can include:

- Wait (delay execution for a period of time — minutes, hours, or days)
- Send WhatsApp Message (Meta-approved templates via the official WhatsApp Cloud API)
- Send SMS (via Twilio)
- Send Email (uses WooCommerce email templates)

Each action can also have its own condition. If that condition fails, the action is skipped.

= How to configure a workflow =

1. Go to **WooCommerce → Messaging Workflows** in your WordPress admin.
2. Open **Settings → Prerequisites** and complete the setup that applies to you (Meta, WhatsApp, Twilio, email, and privacy options).
3. Open **Workflows → Create Workflow** (or edit an existing workflow from **Workflows → Listing**).
4. Enter a **name** and choose a **trigger**. Triggers correspond to WooCommerce events.
5. Add **conditions** if you want to limit which orders or customers qualify (e.g. only orders above a certain total).
6. Add **steps** in order: drag or add actions such as **Wait**, **Send Email**, **Send SMS**, or **Send WhatsApp Message**.
7. Configure each action's fields (template, delay, recipient placeholders, optional per-step conditions).
8. **Save** and set the workflow to **Active** when you are ready.

Test with a real or test order (or an abandoned cart) that matches your trigger and conditions. Open **Workflows → Executions** to inspect queued and completed runs.

= WooCommerce → Messaging Workflows =

The plugin screens live under **WooCommerce → Messaging Workflows**.

**Tabs (primary row)**

1. **Workflows** — List, enable/disable, edit, and delete saved workflows. Sub-sections:
   * **Listing** — Day-to-day workflow management. Create a workflow: trigger, optional conditions, and ordered actions.
   * **Executions** — Queue of workflow runs (pending, waiting, completed, failed).
2. **WhatsApp Templates** — Browse Meta-linked WhatsApp templates, approval status, and shortcuts to manage templates in Meta.
3. **Email Templates** — Opens **WooCommerce → Settings → Emails**, where WooCommerce email templates used by **Send Email** actions are configured.
4. **Settings** — Messaging and integration setup (see sections below).
5. **Documentation** and **Privacy Policy** — Links to the plugin documentation and privacy policy.

**Sections under the Settings tab**

When **Settings** is active, four sections appear:

* **Prerequisites** — Setup checklist (Meta, WhatsApp, Twilio, WooCommerce email) plus plugin privacy options and optional debug logging.
* **Meta App** — Meta app ID, app secret, and optional system user token. The redirect URI should be left as-is and copied into your Meta app settings.
* **WhatsApp Account** — After connecting to Meta, choose the WhatsApp Business Account / phone number used for sending.
* **Twilio Account** — Twilio Account SID, auth token, and sender number for **Send SMS** actions.

= Prerequisites =

Before workflows can send WhatsApp or SMS reliably, complete the following (also summarized under **WooCommerce → Messaging Workflows → Settings → Prerequisites**):

**Meta (WhatsApp)**

* Create a [Meta app](https://developers.facebook.com/docs/development/create-an-app/) with these permissions: `business_management`, `whatsapp_business_management`, `whatsapp_business_messaging`.
* Create a **WhatsApp Business Account** in [Meta Business Suite](https://business.facebook.com/).
* Ensure the WhatsApp Business Account is **approved** by Meta (check status in [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account/)).
* In the plugin, open **WooCommerce → Messaging Workflows → Settings → Meta App**, enter your app credentials, connect to Facebook, then use **WooCommerce → Messaging Workflows → Settings → WhatsApp Account** to select the business asset for messaging.

**WhatsApp message templates**

* Meta requires **approved templates** for most WhatsApp messages.
* After connecting Meta, use **WooCommerce → Messaging Workflows → WhatsApp Templates** to create simple templates; refresh to see approval status. You can also manage templates in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates/).

**Email**

* Email actions use **WooCommerce email templates**. Create or customize them under **WooCommerce → Settings → Emails**.

**SMS (Twilio)**

* SMS actions use **Twilio**. Add your **Account SID**, **Auth Token**, and **From** number under **WooCommerce → Messaging Workflows → Settings → Twilio Account**. You pay Twilio usage costs separately.

**Plugin privacy settings**

Under **Settings → Prerequisites → Plugin Settings**:

* **Ask for consent before sending messages** — Adds a checkout checkbox for WhatsApp/SMS notifications. If disabled, messages may be sent without that checkbox; you must collect consent elsewhere if required.
* **Check for cookie consent before tracking abandoned carts** — When enabled, abandoned-cart tracking runs only if the `afromewo_customer_has_cookie_consented` filter returns true. When disabled, carts are tracked automatically.
* **Debug logging** — Optional. When enabled, entries go to **WooCommerce → Status → Logs** (source `afroit-messaging-workflows`). Disable when finished; logs may contain personal data.

= Actions reference =

Each **action** is one step in your workflow. Many actions support an optional **condition** (variable + operator + value). If that condition fails, the action is skipped.

**Wait**

* **What it does:** Pauses the workflow for a chosen length of time, then continues with the next step.
* **What to configure:** Delay amount, unit (**minutes**, **hours**, or **days**), and optionally a condition so the wait only applies when the condition is met.
* **Note:** Waits use WordPress cron (and a one-minute schedule when available). For reliable delays, ensure WP-Cron is running (or a real system cron hitting `wp-cron.php`).

**Send WhatsApp Message**

* **What it does:** Sends a WhatsApp message using a **Meta-approved template** and order/customer variables.
* **What to configure:** Template (from **WhatsApp Templates**), recipient phone (often a placeholder such as billing phone), optional condition.

**Send SMS**

* **What it does:** Sends an SMS via **Twilio** using your configured account and From number.
* **What to configure:** Message body (can use variables), recipient phone, optional condition. **Twilio** must be configured in settings.

**Send Email**

* **What it does:** Sends an email using a **WooCommerce email template**, with To/Subject supporting placeholders.
* **What to configure:** Email template, To, Subject, optional CC/BCC, optional condition.

= Abandoned carts =

The plugin can snapshot a shopper's cart, detect abandonment, and start a **Shopping Cart Abandoned** workflow.

* Cart contents are stored when items are added or updated, and when checkout email/phone fields are captured (classic and block checkout).
* A cart is treated as abandoned after **60 minutes** without activity (hourly check), if it still has an email or phone and the shopper has not completed checkout.
* Use `{{cart_recovery_url}}` in an email (or other message) so the customer can restore the cart. Recovery requires the original tracking cookie on that browser.

= Example workflows =

**1. Thank-you email after payment**

* **Trigger:** Payment Complete
* **Steps:** Send Email (order confirmation / thank-you template).

**2. WhatsApp order update when order moves to processing**

* **Trigger:** Order Status: Processing
* **Conditions:** (Optional) only for specific shipping methods or totals.
* **Steps:** Send WhatsApp Message (approved "order processing" template).

**3. Abandoned cart reminder (email + wait + second email)**

* **Trigger:** Shopping Cart Abandoned
* **Steps:** Send Email (first reminder, include `{{cart_recovery_url}}`) → **Wait** (e.g. 1 day) → Send Email (second reminder).

**4. Re-engagement a few days after purchase**

* **Trigger:** Payment Complete (or Order Status: Complete)
* **Steps:** **Wait** (e.g. 14 **days**) → Send Email or **Send WhatsApp Message**.
* **Tip:** Use conditions to exclude refunded orders or specific products.

**5. Failed payment: wait, then retry message**

* **Trigger:** Payment Failed
* **Steps:** **Wait** (e.g. 1–2 days) → Send Email or **Send SMS** with a payment retry link.
* **Tip:** Use workflow conditions to target the failed-payment scenarios you want to follow up on.

**6. VIP order: SMS for high-value orders**

* **Trigger:** Payment Complete
* **Conditions:** Order total greater than your VIP threshold.
* **Steps:** Send SMS (Twilio) with a personal thank-you or fulfillment note.

= Support =

* Documentation: [https://messaging-workflows.com/documentation](https://messaging-workflows.com/documentation)
* For bug reports or feature requests, use the support forum on the WordPress.org plugin page.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/afroit-messaging-workflows`, or install the zip from **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** screen. **WooCommerce** must be installed and active. The plugin cannot be activated on WordPress Multisite.
3. Open **WooCommerce → Messaging Workflows**.
4. Go to the **Settings** tab, then **Prerequisites**, and complete setup (Meta, WhatsApp templates, WooCommerce emails, Twilio) as needed.
5. Create your first workflow from **WooCommerce → Messaging Workflows → Workflows → Create Workflow**.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

Yes. This plugin extends WooCommerce orders, checkout, and related events.

= Do I need a Meta app for WhatsApp? =

Yes, if you intend to send WhatsApp messages. You need an approved WhatsApp Business Account and approved templates.

= Do I need Twilio? =

Only if you use **Send SMS** actions.

= Can I use only email and skip WhatsApp and SMS? =

Yes. Configure WooCommerce email templates and use **Send Email** actions only. Meta and Twilio are required only for WhatsApp and SMS.

= Where do workflows run? =

On your WordPress site. Order and cart events are queued and processed locally (WP-Cron / a one-minute schedule when available). No remote workflow API is required.

= Why didn't my workflow run? =

Check that the workflow is **Active**, the **trigger** matches what happened, **conditions** pass, and any **Wait** steps have had time to complete. For abandoned carts, confirm tracking consent (if enabled), that an email or phone was captured, and that about 60 minutes have passed since last cart activity. Use **Workflows → Executions** to inspect runs.

= What variables can I use in messages? =

Placeholders such as `{{billing_phone}}`, `{{phone}}`, `{{user_email}}`, and order-related data. For abandoned-cart emails, `{{cart_recovery_url}}` links to cart restore. See the [template variables documentation](https://messaging-workflows.com/documentation/template-variables).

= Does this plugin support High-Performance Order Storage (HPOS)? =

Yes. Compatibility with WooCommerce custom order tables is declared.

== Screenshots ==

1. WooCommerce → Messaging Workflows — primary tabs: Workflows, WhatsApp Templates, Email Templates, Settings.
2. Settings tab — Prerequisites, Meta App, WhatsApp Account, Twilio Account.
3. Create Workflow — trigger, conditions, and actions.
4. Create WhatsApp Template — text templates with variables and action buttons.
5. WhatsApp Templates — list and approval status.
6. Workflows → Executions — queued and completed runs.
7. Workflow example: review request after order completed.
8. Workflow example: coupon for large purchase amounts.
9. Workflow example: failed payment follow-up.
10. Workflow example: abandoned cart follow-up.
11. Plugin privacy and debug settings.

== Changelog ==

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.

== External services ==

This plugin can connect to the following services when you configure them. Each service may charge its own fees. You are responsible for signing up and complying with each service's terms. The plugin remains usable for email-only workflows without Meta or Twilio.

When a workflow sends a message, order or cart fields used in that message (for example phone, email, name, totals, and other template variables) are sent to the configured service.

= Meta (WhatsApp Cloud API) =

Used to create WhatsApp message templates and to send WhatsApp messages.

* [WhatsApp Business Solution Terms](https://www.whatsapp.com/legal/business-solution-terms)
* [Meta Terms for WhatsApp Business](https://www.whatsapp.com/legal/meta-terms-whatsapp-business)
* [Meta Platform Terms](https://developers.facebook.com/terms/)
* [WhatsApp Business Data Processing Terms](https://www.whatsapp.com/legal/business-data-processing-terms)
* [WhatsApp Privacy Policy](https://www.whatsapp.com/legal/privacy-policy)

= Twilio =

Used to send SMS messages.

* [Twilio Terms of Service](https://www.twilio.com/en-us/legal/tos)
* [Twilio Privacy](https://www.twilio.com/en-us/legal/privacy)

== Third-party libraries and assets ==

= SortableJS 1.15.2 =

* **File:** `assets/js/vendor/sortablejs-1.15.2.min.js`
* **License:** MIT
* **Source:** https://github.com/SortableJS/Sortable

= Plugin CSS and JS =

Plugin CSS and JavaScript in `assets/css` and `assets/js` are compiled with npm into `assets/build`. Production loads the files in `assets/build`.
See `tools/build-assets.mjs`. To rebuild: from the `tools` folder, run `npm run build`.
