WooNooW/NOTIFICATION_SYSTEM.md

Notification System Documentation

Status: ✅ Complete & Fully Wired
Last Updated: November 15, 2025

---

Overview

WooNooW features a modern, flexible notification system that supports multiple channels (Email, Push, WhatsApp, Telegram, SMS) with customizable templates and markdown support.

Key Features

• ✅ Multi-channel support (Email, Push, + Addons)
• ✅ Custom markdown templates with visual builder
• ✅ Variable system for dynamic content
• ✅ Global system toggle (WooNooW vs WooCommerce)
• ✅ Per-channel and per-event toggles
• ✅ Email customization (colors, logo, branding)
• ✅ Async email queue (prevents 30s timeout)
• ✅ Full backend wiring complete

---

Architecture

Structure

Notifications
├── Staff Notifications (toggle channels/events)
├── Customer Notifications (toggle channels/events)
├── Channel Configuration (global settings)
│   ├── Email (template + connection)
│   └── Push (template + connection)
└── Activity Log (coming soon)

Notification Flow

Event → EmailManager → Check System Mode → Check Channel Toggle
→ Check Event Toggle → EmailRenderer → Get Template → Replace Variables
→ Parse Markdown → Apply Branding → Queue via MailQueue → Send

---

Markdown Syntax

Cards

[card:info]
Your content here
[/card]

[card:success]
Success message
[/card]

[card:warning]
Warning message
[/card]

Buttons

[button:solid](https://example.com)
Click Me
[/button]

[button:outline](https://example.com)
Learn More
[/button]

Images

![Alt text](https://example.com/image.png)

---

Variables

Order Variables

• {order_number} - Order number
• {order_date} - Order date
• {order_total} - Order total
• {order_status} - Order status
• {order_items_table} - Formatted table
• {order_items_list} - Formatted list

Customer Variables

• {customer_name} - Customer full name
• {customer_first_name} - First name
• {customer_last_name} - Last name
• {customer_email} - Email address

Store Variables

• {store_name} - Store name
• {store_url} - Store URL
• {store_email} - Store email

---

Backend Integration

API Endpoints

Method	Endpoint	Purpose
GET	/notifications/system-mode	Get current mode
POST	/notifications/system-mode	Switch mode
GET	/notifications/channels	Get all channels
POST	/notifications/channels/toggle	Toggle channel
GET	/notifications/events	Get all events
POST	/notifications/events/update	Update event
GET	/notifications/templates/{id}/{ch}	Get template
POST	/notifications/templates	Save template
GET	/notifications/email-settings	Get email customization
POST	/notifications/email-settings	Save email customization

Database Options

// System mode
woonoow_notification_system_mode = 'woonoow' | 'woocommerce'

// Channel toggles
woonoow_email_notifications_enabled = true | false
woonoow_push_notifications_enabled = true | false

// Event settings
woonoow_notification_settings = [
  'order_processing' => [
    'channels' => [
      'email' => ['enabled' => true, 'recipient' => 'customer']
    ]
  ]
]

// Templates
woonoow_notification_templates = [
  'order_processing_email_customer' => [
    'subject' => '...',
    'body' => '...'
  ]
]

// Email customization
woonoow_email_settings = [
  'primary_color' => '#7f54b3',
  'logo_url' => '...',
  ...
]

---

Email Queue System

Purpose

Prevents 30-second timeout when sending emails via SMTP.

Implementation

• WooEmailOverride: Intercepts wp_mail() calls
• MailQueue: Queues emails via Action Scheduler
• Async Processing: Emails sent in background

Files

• includes/Core/Mail/WooEmailOverride.php
• includes/Core/Mail/MailQueue.php

Initialization

// In Bootstrap.php
MailQueue::init();
WooEmailOverride::init();

---

Key Classes

NotificationManager

File: includes/Core/Notifications/NotificationManager.php

• should_send_notification() - Validates all toggles
• send() - Main sending method
• is_channel_enabled() - Check global channel state
• is_event_channel_enabled() - Check per-event state

EmailManager

File: includes/Core/Notifications/EmailManager.php

• is_enabled() - Check if WooNooW system active
• disable_wc_emails() - Disable WooCommerce emails
• Hooks into WooCommerce order status changes

EmailRenderer

File: includes/Core/Notifications/EmailRenderer.php

• render() - Render email from template
• replace_variables() - Replace variables with data
• parse_cards() - Parse markdown cards
• Applies email customization

TemplateProvider

File: includes/Core/Notifications/TemplateProvider.php

• get_template() - Get custom or default template
• get_variables() - Get available variables
• get_default_template() - Get default template

---

Global System Toggle

Purpose

Allow users to switch between WooNooW and WooCommerce notification systems.

Modes

WooNooW Mode (default):

• Custom templates with markdown
• Multi-channel support
• Full customization
• WooCommerce emails disabled

WooCommerce Mode:

• Standard WooCommerce emails
• WooNooW notifications disabled
• For users who prefer classic system

Implementation

// Check mode
$mode = get_option('woonoow_notification_system_mode', 'woonoow');

// EmailManager respects mode
if (!EmailManager::is_enabled()) {
    return; // Skip WooNooW notifications
}

// NotificationManager checks mode
if ($system_mode !== 'woonoow') {
    return false; // Use WooCommerce instead
}

---

Q&A

Q: Are templates saved and used when sending?

A: ✅ Yes. Templates saved via API are fetched by EmailRenderer and used when sending.

Q: Are channel toggles respected?

A: ✅ Yes. NotificationManager checks both global and per-event toggles before sending.

Q: Does the global system toggle work?

A: ✅ Yes. EmailManager and NotificationManager both check the mode before processing.

Q: Is email sending async?

A: ✅ Yes. MailQueue queues emails via Action Scheduler to prevent timeouts.

Q: Are variables replaced correctly?

A: ✅ Yes. EmailRenderer replaces all variables with actual data from orders/customers.

Q: Does markdown parsing work?

A: ✅ Yes. Cards, buttons, and images are parsed correctly in both visual builder and email output.

---

Related Documentation

• NEW_MARKDOWN_SYNTAX.md - Markdown syntax reference
• NOTIFICATION_SYSTEM_QA.md - Q&A and backend status
• BACKEND_WIRING_COMPLETE.md - Backend integration details
• CUSTOM_EMAIL_SYSTEM.md - Email system architecture
• FILTER_HOOKS_GUIDE.md - Available hooks for customization

---

Future Enhancements

Planned Features

• Activity Log page
• WhatsApp addon
• Telegram addon
• SMS addon
• A/B testing for templates
• Scheduled notifications
• Customer notification preferences page

Addon Development

See ADDON_DEVELOPMENT_GUIDE.md for creating custom notification channels.