Overview

HOMS WhatsApp Order Manager

A premium WooCommerce plugin that routes order confirmations through WhatsApp — giving your customers interactive, one-tap confirm & cancel buttons and your store instant, automatic order status updates.

What it does

Instead of relying on email notifications that go unread, HOMS WhatsApp Order Manager sends your customer a WhatsApp message the moment an order is placed. The message includes order details and two Quick Reply buttons — Confirm Order and Cancel Order. When the customer taps a button, the WooCommerce order status updates automatically and a confirmation message is sent back.

Key Features

Instant WhatsApp Delivery

Order confirmation sent via WhatsApp the moment a customer completes checkout. Zero delay.

Quick Reply Buttons

Twilio Content Template with interactive Confirm & Cancel buttons. One tap — no typing required.

Automatic Status Updates

Button taps update WooCommerce order status instantly — Processing on confirm, Cancelled on cancel.

Custom Message Templates

Four fully editable templates with 10 dynamic placeholders. Customize every word from your dashboard.

Dual Provider Support

Works with both Meta Cloud API and Twilio WhatsApp API. Switch providers from settings without code changes.

Follow-up Reminders

Automatic reminder if a customer hasn't responded within a configurable delay. Fully cancellable.

Retry Queue

Failed messages retry automatically at 5 min, 15 min, and 60 min intervals via Action Scheduler.

Developer Extensible

12+ action hooks and 9 filter hooks. Register custom providers, modify keywords, alter messages.

API Credentials Required: You will need an account with either Twilio or Meta for Developers to send WhatsApp messages. The plugin itself is open-source (GPL-2.0).
Setup

Installation

Get the plugin running on your WordPress + WooCommerce store in under five minutes.

Requirements

Requirement Minimum Version Notes
PHP 8.0+ 8.1+ recommended for best performance
WordPress 6.0+ Latest stable version recommended
WooCommerce 7.0+ HPOS compatible
SSL Certificate Required Webhook endpoints require HTTPS
Action Scheduler Bundled with WC Used for retry queue and reminders
Outbound HTTP Required Server must reach api.twilio.com / graph.facebook.com

Step-by-step Installation

1

Upload the plugin

Navigate to WordPress Admin → Plugins → Add New → Upload Plugin. Choose the homs-whatsapp.zip file and click Install Now.

Alternatively, unzip the archive and upload the homs-whatsapp folder to /wp-content/plugins/ via FTP.

2

Activate the plugin

Go to Plugins → Installed Plugins and click Activate next to HOMS WhatsApp Order Manager.

On activation the plugin automatically:

  • Creates the wp_homs_wa_queue retry database table
  • Seeds all default option values
  • Generates a random Webhook secret token
  • Adds the manage_homs_whatsapp capability to the Administrator role
3

Verify the admin menu

After activation you should see a HOMS WhatsApp menu item in your WordPress admin sidebar. Click it to open the Dashboard page.

Permalinks Notice: After activation, visit Settings → Permalinks and click Save Changes to flush rewrite rules. This is required for the Webhook REST endpoint to work correctly.

Uninstalling

To fully remove the plugin, deactivate it and then delete it from the Plugins screen. The plugin's uninstall routine will automatically remove all stored options and the retry queue database table, leaving your database clean.

Setup

Getting Started

From zero to sending WhatsApp order confirmations in eight steps.

1

Choose your WhatsApp provider

The plugin supports two providers. Choose one that fits your business:

  • Best for Quick Reply buttons (Content Templates)
  • Simple REST API
  • Pay-as-you-go pricing
  • Requires a Twilio WhatsApp-approved number
  • Official WhatsApp Business Platform
  • Higher throughput
  • Requires Meta Business account
  • Template approval required
2

Obtain API credentials

For Twilio: Log in to the Twilio Console, copy your Account SID and Auth Token, and note your WhatsApp-enabled sender number (format: whatsapp:+14155238886).

For Meta: In the Meta for Developers portal, create an App, add the WhatsApp product, and copy your System User Access Token and Phone Number ID.

3

Enter credentials in Settings

Go to HOMS WhatsApp → Settings. Select your provider and fill in the credential fields. For Twilio you will also need to paste your Content Template SID (the HX… identifier from the Twilio Console → Content Template Builder).

4

Create a Twilio Content Template (Twilio only)

In the Twilio Console go to Messaging → Content Template Builder → Create Template. Choose the Quick Reply type. Add two buttons:

  • Button 1 — Label: Confirm Order | Payload: confirm
  • Button 2 — Label: Cancel Order | Payload: cancel

Add body variables such as {{1}} for customer name, {{3}} for order number, etc. Submit the template for approval. Copy the HX… SID into the plugin settings once approved.

5

Configure the Webhook URL

Copy the Webhook URL from the plugin dashboard:

https://yoursite.com/wp-json/homs-whatsapp/v1/webhook

Paste this into:

  • Twilio: Console → Phone Numbers → Your number → Messaging → "A message comes in" → Webhook
  • Meta: App Dashboard → WhatsApp → Configuration → Webhook URL + Verify Token
6

Set a default test phone number

In Settings → General, enter a phone number in E.164 format (e.g. +201012345678) as the default test number. This is used by the Send Test Message button on the dashboard.

7

Test the connection

Click Send Test Message on the Dashboard. You should receive a WhatsApp message on your default phone number within seconds. If not, check the Troubleshooting section.

8

Place a test order

Place a test WooCommerce order using a billing phone number that you can receive WhatsApp messages on. You should receive the confirmation template with the Confirm / Cancel buttons. Tap one — the order status in WooCommerce should update automatically.

Reference

Admin Guide

A complete walkthrough of every screen in the HOMS WhatsApp admin panel.

The Dashboard is the first page you see. It shows:

  • Connection Badge — Live status of the configured provider (Connected / Not configured / Checking…)
  • Webhook URL — Copy button for quick access to the REST endpoint
  • Quick Actions — Send Test Message button
  • Retry Queue Table — Recent queued, pending and exhausted send jobs with order ID, event type, phone, status, and next attempt time
Reference

Frontend Experience

What your customers see from the moment they place an order to receiving a status confirmation.

The Customer Journey

1. Order Placed

Customer completes checkout. The plugin instantly captures the billing phone number, normalises it to E.164 format, and fires the WhatsApp notification pipeline.

2. WhatsApp Message Received

Within seconds, the customer receives a WhatsApp message containing:

  • Their name and the store name
  • Order number, total, payment method
  • List of purchased items
  • Two quick reply buttons: Confirm Order and Cancel Order

3. Customer Taps a Button

The button tap sends a Webhook POST to the plugin. The plugin verifies the HMAC signature, extracts the button payload, looks up the matching order by phone number, and applies the status transition.

4. Confirmation Message Sent

Immediately after the status update, a confirmation message is sent:

  • On confirm: "✅ Your order has been confirmed. We're preparing it now."
  • On cancel: "❌ Your order has been cancelled. If this was a mistake, please contact support."

5. Follow-up (if no response)

If the customer hasn't tapped a button after the configured delay (default: 30 minutes), a follow-up reminder is automatically sent. The reminder is cancelled if the order status changes before the timer fires.

Duplicate Protection: If a customer taps the same button twice (e.g., Confirm twice), the second tap is silently ignored. The plugin checks the current order status before applying any transition.

Phone Number Normalisation

The plugin automatically normalises billing phone numbers to E.164 format. Country-specific rules are applied: 

Egypt (EG):  01012345678  →  +201012345678
Saudi (SA):  0512345678   →  +966512345678
UAE   (AE):  0512345678   →  +971512345678
UK    (GB):  07123456789  →  +447123456789
US    (US):  2125551234   →  +12125551234
Reference

Settings Reference

Complete reference for every option stored in the WordPress options table.

General Options

homs_wa_plugin_enabled
Enable Plugin
Master switch. Set to false to suppress all outgoing messages without deactivating the plugin.
homs_wa_api_provider
Active Provider
Accepted values: meta | twilio
homs_wa_default_phone
Default Test Phone
E.164 format. Used by the Send Test Message button.

Meta Cloud API

homs_wa_meta_access_token
Access Token — Permanent system-user bearer token
homs_wa_meta_phone_id
Phone Number ID — WhatsApp Business phone number ID
homs_wa_meta_app_secret
App Secret — Used to validate HMAC-SHA256 webhook signatures (optional but recommended)
homs_wa_meta_api_version
API Version — Graph API version string. Default: v19.0

Twilio WhatsApp API

homs_wa_twilio_account_sid
Account SID
homs_wa_twilio_auth_token
Auth Token
homs_wa_twilio_from_number
From Number — Must include whatsapp: prefix, e.g. whatsapp:+14155238886
homs_wa_twilio_template_sid
Template SID — Content Template SID for Quick Reply buttons (format: HXxxxxxxxx)

Automation & Retry

homs_wa_notify_new_order
New Order Notification — Boolean
homs_wa_notify_status_changed
Status Change Notification — Boolean
homs_wa_retry_max_attempts
Max Retry Attempts — Integer 1–10. Default: 3
homs_wa_followup_enabled
Follow-Up Enabled — Boolean
homs_wa_followup_delay
Follow-Up Delay — Minutes. Default: 30

Security & Logging

homs_wa_webhook_secret
Webhook Secret — Auto-generated random token. Regenerate by clearing and saving.
homs_wa_log_enabled
Logging Enabled — Boolean
homs_wa_log_retention
Log Retention Days — Integer. Default: 30
Support

Troubleshooting

Solutions to the most common issues. Check the WooCommerce log first: WooCommerce → Status → Logs, filter by homs-whatsapp.

Still stuck? Email support@homseg.com with your WooCommerce log output and a description of the issue.
Advanced

Developer Hooks

Extend the plugin without modifying core files. All hooks follow WordPress conventions.

Action Hooks

Use add_action() to listen for these events.

homs_wa_event_new_order ( int $order_id, array $order_data )

Fires when a new WooCommerce order is processed and the WhatsApp pipeline begins.

homs_wa_button_clicked ( string $phone, string $button )

Fires when an incoming Webhook button click is captured and validated. $button is lowercase/trimmed.

homs_wa_send_success ( string $phone, string $message, string $provider_slug )

Fires after any WhatsApp message is sent successfully.

homs_wa_send_failed ( WP_Error $error, string $phone, string $provider_slug )

Fires when a send attempt fails. The message is queued for retry after this hook.

homs_wa_order_confirmed_via_webhook ( WC_Order $order )

Fires after an order transitions to processing via the Confirm button.

homs_wa_order_cancelled_via_webhook ( WC_Order $order )

Fires after an order transitions to cancelled via the Cancel button.

homs_wa_followup_sent ( int $order_id, string $phone )

Fires after a follow-up reminder is delivered successfully.

homs_wa_retry_succeeded ( int $job_id, int $order_id, string $event_type )

Fires when a queued retry job succeeds.

homs_wa_retry_exhausted ( int $job_id, int $order_id, string $event_type )

Fires when all retry attempts for a job are exhausted. Status is set to exhausted.

Filter Hooks

Use add_filter() to modify these values.

homs_wa_register_providers ( array $registry )

Register a custom provider class. Return the array with your provider slug mapped to its class name. 

add_filter( 'homs_wa_register_providers', function( $registry ) {
    $registry['my_provider'] = My_Custom_Provider::class;
    return $registry;
} );
homs_wa_confirm_keywords ( array $keywords )

Modify the list of message body strings that map to a confirm intent. Default: ['confirm', 'yes', '1', 'تأكيد', ...]

homs_wa_cancel_keywords ( array $keywords )

Modify the list of strings that map to a cancel intent. Default: ['cancel', 'no', '2', 'إلغاء', ...]

homs_wa_rendered_message ( string $rendered, string $event_type, array $order_data )

Filter the final rendered message body before it is sent. Useful for appending legal disclaimers or modifying formatting.

homs_wa_template_{event_type} ( string $template )

Filter the raw template string for a specific event. Replace {event_type} with new_order, order_confirmed, order_cancelled, or follow_up. 

add_filter( 'homs_wa_template_new_order', function( $template ) {
    // Append a custom footer to the new order message
    return $template . "\n\n---\nPowered by My Store";
} );