Omnirely Order Connect for WooCommerce

Description

Sends template-based customer notifications automatically on WooCommerce order, customer, shipping and cart events
(order created, paid, processing, completed, cancelled, refunded, shipped, customer created,
abandoned cart and abandoned-cart discount follow-up) via the Omnirely API. Built as an automation bridge, not a
raw API pass-through: every send goes through a rule engine (event +
conditions + template + parameter mapping) and a background queue, so
checkout and order processing are never blocked by an outbound WhatsApp API
call.

What’s implemented (V1 / Phases 1–3)

• Connection screen: API URL + API key, “Connect & Verify” against
  Omnirely’s /connection endpoint, key stored encrypted.
• Template sync: pulls approved templates from Omnirely, caches locally,
  re-syncs twice daily via WP-Cron, extracts {{n}} placeholders per
  template automatically.
• Automation builder: event -> conditions -> template -> parameter mapping.
  Parameter mapping now follows the WhatsApp template standard fully:
  placeholders are detected and mapped separately for the Header (0 or 1
  text parameter), Body (N parameters), and dynamic URL Buttons (1
  parameter each), each with the same dynamic variable library
  (customer/order/billing/shipping/store/item fields) so merchants pick
  fields from dropdowns rather than typing variable names.
• Send payloads are built as the standard WhatsApp components array
  (one entry per header/body/button component, each with its own
  resolved parameters) — see Omnirely_Variable_Resolver::resolve_components().
• WooCommerce hooks for: new order, paid/processing, on-hold, completed,
  cancelled, failed, refunded, shipped (via tracking-number meta or a
  custom “shipped” status), new customer.
• Action Scheduler-backed queue: every send is logged first (status:
  queued), then processed as a background job with retry/backoff on
  transient failures (network errors, 5xx) and no retry on permanent ones
  (bad template, invalid number).
• Message Logs screen with status filter and stored API errors.

What’s scaffolded (Phase 4–5, ready to extend)

• Abandoned cart tracking (class-omnirely-cart-tracker.php): identifies
  a phone number from a logged-in customer’s profile or a phone entered
  at checkout, tracks cart contents/total, and schedules a two-stage
  reminder (configurable hours) via Action Scheduler. Carts with no
  identifiable phone are stored but never scheduled for a reminder.
  Create the matching “cart_abandoned” / “cart_abandoned_followup”
  automations on the Automations screen to activate it.
• Condition engine supports payment status, order total, payment method,
  shipping country, product category, and (for carts) cart total /
  product category — extend via the omnirely_wc_condition_field_value
  filter.
• Coupon/discount-on-second-reminder: the DB schema and cart settings
  screen are in place; wiring a specific coupon code into the stage-2
  template parameters is a short addition to
  Omnirely_Cart_Tracker::check_cart().
• A full drag-and-drop flow builder (multi-step delays/branches beyond
  the two cart stages) is intentionally out of scope for V1, per the
  phased rollout plan — the current event+condition+template model is
  built to not require a rewrite when that’s added later.

Before going live

• The send-message endpoint is confirmed as POST /whatsapp/messages (relative
  to your configured API URL) per
  https://dev.omnirely.com/api/docs#/Messages%20API/post_api_v1_whatsapp_messages,
  and the request payload follows the WhatsApp Business Platform standard
  components structure (header/body/button, each with type/text or
  type/sub_type/index and a parameters array).
• The templates-list endpoint is assumed to be GET /whatsapp/templates by
  the same naming convention — this page’s content is rendered client-side
  by a Swagger UI, so it couldn’t be fetched directly to confirm. If the
  Templates tab’s “Sync Templates” fails or its raw-response debug panel
  shows a 404, check that page’s “Templates API” section and update the
  path in includes/class-omnirely-api-client.php -> get_templates()
  accordingly.
• Media headers (IMAGE/VIDEO/DOCUMENT) are detected but not yet mappable
  to a dynamic per-order value — the automation form notes when a
  template has one; wiring a static media URL per automation is a short
  addition to the parameter map and resolve_components() if needed.
• Decide the phone-number source of truth (omnirely_wc_order_phone
  filter is provided) if billing phone isn’t reliably in WhatsApp E.164
  format for your customer base — you’ll likely want a normalization step.
• Load-test the Action Scheduler queue if you expect high order volume;
  Action Scheduler batches by default and is already what WooCommerce
  itself relies on for background jobs.

0.3.0

• Fixed Action Scheduler callback argument handling so queued jobs reach the message processor.
• Added a one-minute queue watchdog WP-Cron event to recover queued jobs whose scheduled action did not start.
• Added worker/watchdog heartbeat options and per-message locking to reduce duplicate sends.
• Existing queued entries are recovered when their stored payload is valid.

0.4.4

• Simplified the WooCommerce sidebar by removing the separate Connection, Templates, Automations, Abandoned Cart, and Message Logs menu items. The Omnirely dashboard entry remains.

0.5.3

• Added custom fixed-text input for each mapped template header, body, and dynamic URL button parameter.
• Custom parameter text takes priority over the selected WooCommerce variable and is resolved as a literal string when sending.

0.5.5

• Connection screen now defaults to the Omnirely WhatsApp API URL.
• Added a direct Omnirely login link and Developer API key instructions.