WhatsApp Notifications for WooCommerce

Overview

WooNotify connects your WooCommerce store directly to the Meta WhatsApp Cloud API. Every time an order status changes, a WhatsApp notification is sent to the customer's phone using a pre-approved Meta Message Template. The plugin also detects abandoned carts and sends a recovery message 1 hour later — all without any third-party relay service.

How it works at a glance

Key features

• 7 notification triggers — Payment Confirmed, Shipped, Out for Delivery, Completed, Cancelled, Refunded, Abandoned Cart
• Meta Message Template support — the only way to reliably send business-initiated WhatsApp messages
• Queue & retry system — messages are queued in the database; failed messages auto-retry up to 3 times
• Abandoned cart recovery — detects incomplete checkouts and sends a recovery link via WhatsApp
• Custom order statuses — adds "Shipped" and "Out for Delivery" to WooCommerce
• Tracking number field — enter tracking info per order and include it in notifications
• HPOS compatible — works with WooCommerce High-Performance Order Storage
• Full message log — view, retry, delete, and export all messages as CSV
• Customer opt-in — GDPR/TRAI-compliant checkbox on checkout (unchecked by default)

Requirements

Installation

1. Upload the plugin

   Upload the order-notify-for-woocommerce folder to your /wp-content/plugins/ directory, or install via Plugins → Add New → Upload Plugin in the WordPress admin.

2. Activate

   Go to Plugins → Installed Plugins and activate WhatsApp Notifications for WooCommerce. The plugin will automatically create two database tables (wp_wanc_log and wp_wanc_abandoned) and schedule WP-Cron events.

3. Configure Meta API credentials

   Go to WA Notify → Settings → API Setup and enter your Phone Number ID and System User Access Token. See the Meta API Setup section below for step-by-step instructions.

4. Create and configure message templates

   In Meta Business Manager, create approved Message Templates for each notification type. Then enter the template names under WA Notify → Settings → Templates.

5. Send a test message

   Enter your phone number in the API Setup tab and click Send Test to verify the connection is working.

Meta API Setup

This is the most important step. Follow these instructions carefully to obtain the correct credentials.

Step 1 — Create a Meta Business App

1. Go to Meta Developers

   Visit developers.facebook.com and click My Apps → Create App.

2. Choose "Business" type

   Select Business as the app type. This unlocks WhatsApp API access.

3. Add WhatsApp product

   In your app dashboard, find Add Products and click Set Up next to WhatsApp.

4. Link your WhatsApp Business Account

   Follow the prompts to connect an existing WhatsApp Business Account or create a new one.

Step 2 — Get your Phone Number ID

1. Navigate to WhatsApp → API Setup

   In your Meta App dashboard, go to WhatsApp → API Setup in the left sidebar.

2. Find Phone Number ID

   Under the "From" section, you will see your phone number listed. Below or beside it is the Phone Number ID — a long numeric string like 1234567890123456. This is what you need.

Step 3 — Create a Permanent System User Token

1. Go to Meta Business Settings

   Visit business.facebook.com/settings and navigate to Users → System Users.

2. Create a System User

   Click Add, give it a name (e.g., "WooCommerce Notifier"), and set role to Admin.

3. Assign assets

   Click Add Assets → select your WhatsApp Business Account → grant Full Control.

4. Generate a token

   Click Generate New Token → select your app → check whatsapp_business_messaging and whatsapp_business_management permissions → set expiration to Never → Generate.

5. Copy and save the token immediately

   This token is shown only once. Copy it and paste it into the plugin's Permanent System User Token field.

Step 4 — Create Message Templates

Before you can send notifications, you must create approved Message Templates in Meta. WhatsApp does not allow businesses to send free-form text messages to customers who haven't contacted them first.

1. Go to WhatsApp Manager

   In Meta Business Manager → WhatsApp Manager → Message Templates.

2. Create a template

   Click Create Template. Choose category Utility or Marketing, give it a name (lowercase letters, numbers, underscores only — e.g., order_confirmed), and select a language.

3. Write the body with variables

   Use positional variables like {{1}}, {{2}} for dynamic content. For example:

   Hi {{1}}! Your order #{{2}} has been confirmed.
   Total: {{3}}
   Thank you for shopping with {{4}}!

4. Submit for review

   Templates are usually approved within a few minutes to a few hours.

Settings — API Setup Tab

Meta Cloud API Credentials

Test & Admin Notifications

Validate Connection button

Clicking Validate Connection calls the Meta Graph API to verify your Phone Number ID and token are correct. On success, it shows the business account name. On failure, it shows the exact Meta error message.

Settings — Notifications Tab

Enable or disable each notification trigger independently. Each trigger has its own toggle switch.

Settings — Templates Tab

Each trigger has its own template card where you configure how the message is sent.

Available Variables (Preview Only)

These variables can be used in the free-form preview field and as values in the Parameter Mapping field:

Settings — Checkout Tab

Order Triggers — How They Work

The plugin listens to WooCommerce's order status change hooks. When an order moves to a status that has a trigger configured and enabled, and the customer opted in, the plugin:

1. Reads the trigger's template name and parameter mapping from settings
2. Resolves variable values from the live order (customer name, order total, etc.)
3. Builds a JSON payload with the template name and resolved parameters
4. Inserts a row into the message queue table (wp_wanc_log) with status queued
5. WP-Cron picks it up within 2 minutes and calls the Meta API

Meta Message Templates

Why templates are required

WhatsApp's Cloud API distinguishes between two types of messages:

Since WooCommerce order notifications are always business-initiated (the store sends first), they must use approved Message Templates. Free-form messages will appear as sent in the log but will not be delivered.

Template naming rules

• Lowercase letters, numbers, and underscores only
• No spaces or special characters
• Examples: order_confirmed, order_shipped, abandoned_cart_recovery

Template variables (positional)

Meta templates use positional variables: {{1}}, {{2}}, {{3}}, etc. The plugin's Parameter Mapping field maps plugin variables to these positions.

Example

Meta template body:

Hi {{1}}! Your order #{{2}} worth {{3}} has been shipped.
Tracking: {{4}}
— {{5}}

Plugin parameter mapping:

{{customer_name}},{{order_id}},{{order_total}},{{tracking_number}},{{site_name}}

Result sent via API:

{{1}} = "John"
{{2}} = "1042"
{{3}} = "₹1,499.00"
{{4}} = "BD123456IN"
{{5}} = "My Store"

Template Variables Reference

All variables available to use in the Parameter Mapping field and free-form preview templates:

Abandoned Cart Recovery

The abandoned cart feature automatically detects when a customer starts filling out the checkout form but leaves without completing their purchase — and sends them a WhatsApp message 1 hour later with a link to recover their cart.

How it works

1. Customer fills checkout form

   On the checkout page, the plugin injects a small JavaScript snippet. When the customer types their phone number AND checks the WhatsApp opt-in checkbox, the script waits 2 seconds (to avoid firing on every keystroke), then sends the phone and cart contents to a background AJAX endpoint.

2. Cart session saved

   The AJAX handler saves the session to the wp_wanc_abandoned table with status active, along with a unique recovery token, the phone number, and the cart contents (product IDs, quantities, variations).

3. Customer places order — session marked recovered

   If the customer completes checkout, the plugin immediately marks the cart session as recovered. No notification is sent.

4. Cron checks every 30 minutes

   WP-Cron runs the abandoned cart check every 30 minutes. It looks for sessions that are still active and were created more than 1 hour ago.

5. Recovery message sent

   For each qualifying cart, the plugin queues an abandoned cart notification using your configured Meta template. The session status is updated to notified.

6. Customer clicks recovery link

   If the customer clicks {{cart_link}} in the WhatsApp message, WooCommerce restores their cart items and redirects them to the cart page. The session status is updated to recovered.

Requirements for abandoned cart to work

• The Abandoned Cart trigger must be enabled in WA Notify → Settings → Notifications
• A Meta Template Name must be configured in the Templates tab for the Abandoned Cart card
• The customer must enter their phone number AND check the opt-in checkbox on the checkout page
• WP-Cron must be running — see the WP-Cron section

Recommended template for abandoned cart

Create a Meta template with these variables and use the following parameter mapping:

Meta Template Body:
Hi {{1}}! You left something in your cart 🛒

Your cart total: {{2}}

Complete your order here:
{{3}}

— {{4}}

Parameter Mapping:

{{customer_name}},{{order_total}},{{cart_link}},{{site_name}}

Tracking Numbers

The plugin adds a "WhatsApp Tracking Number" field to the WooCommerce order edit screen, displayed below the shipping address section.

How to use it

1. Go to WooCommerce → Orders and open an order
2. Scroll down to the Shipping section — you'll see the "WhatsApp Tracking Number" input
3. Enter a tracking number or full tracking URL (e.g., BD123456IN or https://track.dhl.com/BD123456IN)
4. Click Save Order

The value is automatically available as {{tracking_number}} in all notification templates. If no tracking number is set, it resolves to N/A.

Custom Order Statuses

WooCommerce does not include "Shipped" or "Out for Delivery" statuses by default. This plugin registers both:

These statuses appear in the WooCommerce order status dropdown in the correct position in the fulfilment workflow:

Message Log

The Message Log (WA Notify → Message Log) shows every message the plugin has queued, sent, or failed. It is the primary tool for monitoring and troubleshooting.

Message statuses

Log actions

WP-Cron status banner

The top of the Message Log shows the current cron schedule. If WP-Cron events are not scheduled (which can happen after some caching plugins clear scheduled events), the banner shows a warning. The plugin automatically reschedules the cron on every WordPress page load via a self-healing mechanism.

Testing

Testing the API connection

1. Go to WA Notify → Settings → API Setup
2. Enter your phone number in Your Phone Number
3. In Test Template Name, enter hello_world (Meta's built-in template — no variables, always approved)
4. Click 📱 Send Test
5. You should receive a WhatsApp message within seconds

Testing a template with variables

1. Set Test Template Name to your template (e.g., order_confirmed)
2. In Test Variables, enter comma-separated sample values matching your template's variable count.
   Example for a 3-variable template: John, 1042, ₹1499
3. Click 📱 Send Test

Testing order notifications end-to-end

1. Place a test order in WooCommerce and check the WhatsApp opt-in checkbox
2. Set order status to Processing — this fires the Payment Confirmed trigger
3. Check WA Notify → Message Log — the message should appear as Queued
4. Click ⚡ Process Queue Now to send immediately (instead of waiting for cron)
5. The status should change to Sent and you should receive the WhatsApp message

Testing abandoned cart

1. Open an incognito/private browser window
2. Add a product to cart and proceed to checkout
3. Enter your phone number and check the WhatsApp opt-in checkbox
4. Wait 2 seconds (the tracker script fires after a 2-second debounce)
5. Navigate away from the checkout page without placing an order
6. Check wp_wanc_abandoned in your database — a row with status = 'active' should appear
7. After the 1-hour threshold, click ⚡ Process Queue Now to trigger the abandoned cart check manually (or wait for cron)

WP-Cron

WP-Cron is WordPress's built-in task scheduler. This plugin schedules two recurring events:

How WP-Cron works

WP-Cron is pseudo-cron — it runs when someone visits a page on your website, not on a real time schedule. On high-traffic sites, timing is accurate. On low-traffic sites or local development environments, cron events may be delayed or may never run.

Self-healing cron

The plugin includes a self-healing mechanism. On every WordPress page load, it checks if both cron events are scheduled and reschedules them if they are missing (which can happen when caching plugins clear scheduled events or after WordPress updates).

Setting up a real server cron (recommended for production)

For reliable timing on production sites, disable WP-Cron and use a real server cron job instead:

define( 'DISABLE_WP_CRON', true );

* * * * * php /path/to/wordpress/wp-cron.php > /dev/null 2>&1
# or via WP-CLI:
* * * * * cd /path/to/wordpress && wp cron event run --due-now > /dev/null 2>&1

Testing on localhost (XAMPP/WAMP)

On a local development machine, no external traffic visits your site so WP-Cron never fires automatically. Use the ⚡ Process Queue Now button in the Message Log to trigger queue processing manually whenever you want to test.

Database Schema

The plugin creates two custom tables during activation using dbDelta() (WordPress's safe table creation utility).

message_body format

When a Meta Message Template is configured, message_body is stored as a JSON object:

{
  "_wanc_tpl": 1,
  "name": "order_confirmed",
  "params": ["John", "1042", "₹1,499.00", "Processing", "N/A", "My Store"],
  "preview": "Hi John! Your order #1042 has been confirmed. Total: ₹1,499.00"
}

The _wanc_tpl flag tells the queue processor to use send_template() instead of send_text(). The preview field is displayed in the Message Log for human readability.

Cleanup on uninstall

When the plugin is deleted (not just deactivated) via Plugins → Delete, the uninstall.php script automatically:

• Drops wp_wanc_log and wp_wanc_abandoned tables
• Deletes the wanc_settings and wanc_version options from wp_options
• Clears all scheduled WP-Cron events

Privacy & Data

Data sent to Meta

When a notification is sent, the following data is transmitted to Meta's servers at graph.facebook.com:

• Customer phone number (in E.164 format)
• Template name and variable values (may include: customer name, order ID, order total, order status, tracking number, site name, cart recovery URL)

No payment information (card numbers, bank details) is ever sent.

Data stored locally

The following data is stored in your WordPress database:

• wp_wanc_log: Phone number, order ID, message content, delivery status, Meta message ID
• wp_wanc_abandoned: Phone number, WooCommerce session ID, cart product IDs and quantities, cart total, recovery token
• wp_wanc_settings (wp_options): Phone Number ID, access token (stored in plaintext — protect your database), API settings, trigger configurations

Consent

The plugin adds an opt-in checkbox to the WooCommerce checkout form. Notifications are only sent to customers who explicitly check this box. The checkbox is unchecked by default, complying with GDPR, TRAI, and similar regulations.

Troubleshooting

Error: "Object with ID does not exist"

Error: "#132000 Number of parameters does not match"

Error: "Template name does not exist in the translation"

Messages stay in "Queued" status

API connected but WhatsApp message not received

Test button always sends hello_world instead of my template

Abandoned cart notification not sending

Custom order statuses (Shipped / Out for Delivery) not visible in WooCommerce

Frequently Asked Questions

Does this plugin require a subscription or monthly fee?

No. The plugin itself is free. You pay only Meta's standard WhatsApp Cloud API rates — 1,000 conversations per month are free, and beyond that pricing varies by country and conversation type.

What is the difference between a "conversation" and a "message"?

Meta charges per 24-hour conversation window, not per individual message. If you send 5 messages to the same customer within 24 hours, it counts as 1 conversation.

Can I send images or attachments in notifications?

Not in the current version. The plugin supports text-only Message Templates. Meta also supports header images in templates — this may be added in a future version.

Does the customer need to have WhatsApp installed?

Yes. Messages are sent via WhatsApp. If the customer's phone doesn't have WhatsApp, the message won't be delivered.

Is the plugin compatible with WooCommerce HPOS?

Yes. The plugin declares HPOS compatibility and uses WooCommerce's order object API ($order->get_meta(), $order->update_meta_data()) instead of direct post meta functions.

What happens to the customer's data if I uninstall the plugin?

When you delete (not just deactivate) the plugin via WordPress admin, the uninstall script drops both database tables and removes all plugin options. All customer phone numbers and cart data stored by the plugin are permanently deleted.

Can I use multiple WhatsApp phone numbers?

The current version supports one WhatsApp Business phone number per WordPress installation. Multi-number support may be added in a future version.

How do I get a long-lived access token?

Use a System User token from Meta Business Settings → System Users. System User tokens don't expire (unless you set an expiration date or revoke them). This is different from the user access token or the temporary token shown in the Meta Developer Console.

What Meta API version does the plugin use?

The plugin uses Meta Graph API v25.0 via the endpoint https://graph.facebook.com/v25.0/.

Why does the plugin queue messages instead of sending immediately?

Sending via WP-Cron queue has several advantages: it doesn't slow down the checkout/order-save process, it allows automatic retries if Meta's API is temporarily unavailable, and it provides a full audit log of all messages.