Notifications

Status: 🟢 Production (email + WhatsApp live; in-app + push low-volume) · Last validated: 2026-09-06

Multi-channel delivery: in-app, push (FCM + Web Push), email, SMS, WhatsApp. Validated against classs/PushNotificationModule.php, classs/KvMailService.php, classs/KvWhatsAppCloud.php + schema.

Channels & stores (2026-09-06)

Drift caught: fp_notify (referenced in some older notes) is not present in this DB — the in-app store is notifications. notification_master/notification_queue/sms_log also do not exist. Validate the channel table before writing to it.

Email (KvMailService, static API)

• KvMailService::queue(to, subject, htmlBody, opts): int (:160) — enqueue to email_queue.
• recipientDeliverable(email) (:44) — suppression/deliverability check.
• template(key) (:98) + render(tpl, vars) (:110) — templated mail from email_templates.
• userAllows(userId, category) (:139) — respects per-user notification preferences before

sending. Always honored.

• htmlToText(html) (:127) — plain-text alt.
• Delivery: the cron/email_queue_processor.php cron drains email_queue.

Push (PushNotificationModule)

• saveWebPushSubscription(userId, subscription) (:72), saveFcmToken(userId, token, deviceType)

(:121) — register endpoints (push_subscriptions + FCM tokens).

• sendToUser(userId, title, body, url, data) (:197), sendToUsers(userIds, …) (:470) — send.
• removeSubscription (:160), getUserSubscriptions (:179).

WhatsApp

KvWhatsAppCloud (Cloud API) writes wa_outbound; inbound + FAQ via KvWhatsAppFaqBot (the "Rishi" bot). Outbound is gated to opted-in contacts (wa_optins) — see memory whatsapp-outbound-reality. Template sync via cron/wa_template_sync.php.

The event → notification pattern

Business event (order placed, KYC approved, new lead, refund…)
  → module decides channels + recipient
  → KvMailService::userAllows(userId, category)  (pref gate)
  → per channel: notifications (in-app) · KvMailService::queue (email) · PushNotificationModule::sendToUser · KvWhatsAppCloud (WhatsApp)
  → cron workers deliver (email_queue_processor, marketing_*_worker, social_media_publisher)

Representative events (fill per module)

Order created/accepted/dispatched/delivered; payment success/failure; refund initiated/completed; booking confirmed; KYC approved/rejected; new lead; new message; membership renewal reminder. Each module's page section J lists its own events.

Business rules

• BR-NOTF-001 — always gate on KvMailService::userAllows(userId, category) before user email.
• BR-NOTF-002 — WhatsApp outbound only to opted-in contacts (wa_optins).
• BR-NOTF-003 — email is queued (email_queue) and delivered by cron, never sent inline on the request.

Errors (prefix NOTF-E)

• NOTF-E001 email not delivered — check email_queue status + email_queue_processor cron +

recipientDeliverable suppression.

• NOTF-E002 push not received — no push_subscriptions/FCM token for the user.
• NOTF-E003 WhatsApp not sent — recipient not in wa_optins.

Change-impact

Every module fires notifications; changing the pref gate or a channel affects all of them. Re-test: pref gate honored, email queued+drained, push to a subscribed user, WhatsApp to an opted-in contact.