Notifications & Automation

The notification system enables automated email communications triggered by booking lifecycle events. This guide covers managing email templates and configuring automation rules.

Overview

The notification automation system consists of two main components:

1. Email Templates: Customizable templates for booking-related emails
2. Automation Rules: Trigger conditions that send notifications automatically

Email Templates

Email templates define the content of automated notifications. Templates can be customized at three levels: global (platform default), tenant (business-wide), and site (brand-specific). Each level can be localized for different languages.

Managing Templates

Navigate to Catalog > Email Templates in the admin panel.

Template List View:

• Filter by template key, locale, or active status
• Toggle templates on/off without deleting
• Preview templates with sample data

Creating a Template

Click Create Template and fill in the following:

Required Fields:

Field	Description
Template Key	System identifier (e.g., booking_confirmed)
Language	Language code (e.g., en, fi)
Subject	Email subject line (supports {{variables}})
Body	Email content (HTML with {{variables}})

Optional Settings:

Field	Description
Site	Target site for brand-specific templates (blank = tenant-wide)
Type	email (default) or sms

Template Keys

The system supports these template types:

Booking Lifecycle:

Key	When Sent	Site-Specific
booking_confirmed	When booking is confirmed	Yes
booking_reminder	Before booking date	Yes
booking_canceled	When booking is cancelled	Yes
booking_rescheduled	When booking time changes	Yes
status_changed	When booking status changes	Yes

Account Management:

Key	When Sent	Site-Specific
email_verification	New account registration	No
password_reset	Password reset request	No
email_change_verification	Email change (sent to new address)	No
email_change_security	Email change (alert to old address)	No
account_deletion_confirmation	Account deleted	No

Gift Cards & Other:

Key	When Sent	Site-Specific
gift_card_purchase_confirmation	Gift card purchased	Yes
gift_card_delivery	Gift card delivered to recipient	Yes
invitation_email	Team member invited	No
review_request	After booking completion	Yes

Templates marked Site-Specific = Yes can have brand-specific versions per site. Account-level templates are always tenant-wide since customers may book across multiple brands.

Using Variables

Templates use Handlebars syntax for dynamic content:

Customer Information:

{{customerName}}
{{customerEmail}}
{{customerPhone}}

Booking Details:

{{bookingReference}}
{{bookingDateTime}}
{{partySize}}
{{productName}}
{{siteName}}
{{siteAddress}}

Business Information:

{{businessName}}
{{supportEmail}}
{{supportPhone}}

Date Formatting:

{{formatDate bookingDateTime 'MMMM d, yyyy'}}
{{formatDate bookingDateTime 'h:mm a'}}

Currency Formatting:

{{formatCurrency totalAmount currency}}

Conditionals:

{{#if siteAddress}}
  Address:
  {{siteAddress}}
{{/if}}

Template Example

Subject:

Your booking at {{businessName}} is confirmed!

Body:

Hi
{{customerName}}, Your booking has been confirmed! **Booking Details:** -
Reference:
{{bookingReference}}
- Activity:
{{productName}}
- Date:
{{formatDate bookingDateTime 'MMMM d, yyyy'}}
- Time:
{{formatDate bookingDateTime 'h:mm a'}}
- Party Size:
{{partySize}}

**Location:**
{{siteName}}
{{#if siteAddress}}{{siteAddress}}{{/if}}

{{#if totalAmount}}
  **Total Paid:**
  {{formatCurrency totalAmount currency}}
{{/if}}

We look forward to seeing you!

{{businessName}}
{{#if supportEmail}}Contact: {{supportEmail}}{{/if}}

Template Resolution Chain

When sending a notification, the system resolves the best template using a single prioritized query:

1. Site + tenant template for the requested language
2. Tenant template (no site) for the requested language
3. Global template for the requested language
4. Site + tenant template for English (fallback)
5. Tenant template for English (fallback)
6. Global template for English (fallback)
7. Built-in TypeScript template (hardcoded last resort)

For booking lifecycle emails, the system automatically uses the booking's siteId to find brand-specific templates. Account-level emails (password reset, verification) skip site resolution entirely.

Example: A cancellation email for a Laserareena booking in Finnish:

• First checks for a Laserareena-specific Finnish template
• Falls back to a tenant-wide Finnish template
• Falls back to a global Finnish template
• If no Finnish template exists, tries English at each level
• Last resort: built-in TypeScript template

Template Seeding (File-Based)

Templates can be managed via HTML files in the seed directory:

packages/db/seeds/templates/
├── _global/fi/           → Global defaults (any tenant)
├── _tenant/fi/           → Tenant-level (Active Entertainment)
├── laserareena/fi/       → Site-specific (Laserareena Helsinki)
├── korkee/fi/            → Brand folder → maps to both Korkee sites
└── ...

Each brand folder maps to one or more site IDs. Place {templateKey}.html files in the language subdirectory. Optional {templateKey}.subject.txt files override the default subject line.

Run pnpm -F @booking/db seed:templates to upsert all templates to the database.

Preview Templates

Before saving, click Preview to see how the template renders with sample data. This helps verify:

• Variable substitutions work correctly
• Date/currency formatting is correct
• Conditional logic displays properly
• Overall layout and content

Automation Rules

Automation rules define when and how notifications are triggered based on booking events.

Managing Rules

Navigate to Catalog > Automation Rules in the admin panel.

Rule List View:

• Filter by trigger event or active status
• Toggle rules on/off without deleting
• View timing and template configuration

Creating a Rule

Click Create Rule and configure:

Basic Information:

Field	Description
Rule Name	Descriptive name (e.g., "24-Hour Reminder")
Description	Optional explanation of the rule
Is Active	Enable/disable the rule

Trigger Configuration:

Field	Description
Trigger Event	When the rule activates
Offset	Time before/after the event
Offset Unit	Hours or Days
Template	Which email template to use

Trigger Events

Event	Description	Use Cases
Booking Created	When a new booking is made	Confirmation, instructions
Booking Confirmed	When payment is confirmed	Receipt, reminders
Booking Completed	When booking is marked complete	Feedback requests
Relative to Booking Date	Based on booking start time	Reminders, day-of instructions

Timing Configuration

Offset Values:

• Positive values: Send after the event (e.g., +2 hours = 2 hours after)
• Negative values: Send before the event (e.g., -24 hours = 24 hours before)
• Zero: Send immediately when the event occurs

Common Configurations:

Rule	Trigger	Offset
Instant confirmation	Booking Confirmed	0 hours
24-hour reminder	Booking Date	-24 hours
1-week reminder	Booking Date	-7 days
Follow-up survey	Booking Completed	+1 day

Filtering Rules

Rules can be scoped to specific products or sites:

Product Filter:

• Leave empty to apply to all products
• Select specific products for targeted notifications

Site Filter:

• Leave empty to apply to all sites
• Select specific sites for location-specific messaging

Rule Examples

Example 1: Booking Confirmation

Name: Instant Booking Confirmation
Trigger: Booking Confirmed
Offset: 0 hours
Template: booking_confirmation
Products: All
Sites: All

Example 2: Pre-Booking Reminder

Name: 24-Hour Booking Reminder
Trigger: Relative to Booking Date
Offset: -24 hours
Template: booking_reminder
Products: All
Sites: All

Example 3: VIP Experience Reminder

Name: VIP Experience - 48 Hour Reminder
Trigger: Relative to Booking Date
Offset: -48 hours
Template: vip_reminder
Products: VIP Experience, Premium Package
Sites: All

Example 4: Feedback Request

Name: Post-Booking Feedback
Trigger: Booking Completed
Offset: +24 hours
Template: feedback_request
Products: All
Sites: All

How Notifications Work

Notification Queue

When a rule triggers, notifications are queued for delivery:

1. Event Detection: System detects booking lifecycle event
2. Rule Matching: Finds active rules matching the event
3. Scheduling: Calculates send time based on offset
4. Queue Insert: Notification added to processing queue
5. Delivery: Worker processes queue and sends emails

Delivery Status

Notifications can have these statuses:

Status	Description
pending	Queued, waiting for send time
sent	Successfully delivered
failed	Delivery failed after all retries

Retry Logic

Failed notifications are automatically retried:

• Max Retries: 3 attempts
• Backoff: Exponential (1 min, 2 min, 4 min)
• Final Status: Marked as failed after all retries exhausted

Date-Based Rule Scanner

For Relative to Booking Date rules, a daily scanner ensures reminders aren't missed:

• Runs: Daily at 2 AM (configurable)
• Scans: Confirmed bookings within 14 days
• Deduplication: Won't create duplicate notifications

Best Practices

Template Design

1. Keep It Simple: Clear, concise content
2. Mobile-Friendly: Short paragraphs, clear formatting
3. Include Essentials: Date, time, location, reference number
4. Add Contact Info: How to reach support
5. Test Thoroughly: Preview with different data scenarios

Automation Strategy

1. Don't Over-Notify: 2-3 key touchpoints maximum
2. Appropriate Timing: Not too early, not too late
3. Relevant Content: Match template to trigger purpose
4. Segment When Needed: Use product/site filters
5. Monitor Delivery: Check for failed notifications

Common Setups

Basic Setup (All Businesses):

1. Booking confirmation (immediately on confirm)
2. 24-hour reminder (day before)

Premium Setup (High-Touch):

1. Booking confirmation (immediately)
2. 1-week reminder (if booked far in advance)
3. 24-hour reminder (final reminder)
4. Feedback request (day after)

Minimal Setup (Low-Touch):

1. Booking confirmation (immediately)

Troubleshooting

Notifications Not Sending

1. Check Rule is Active: Toggle may be off
2. Verify Template Exists: Rule must have valid template
3. Check Scheduling: Date-based rules queue for future
4. Review Logs: Check notification delivery log

Wrong Content in Emails

1. Preview Template: Verify variable substitution
2. Check Template Key: Rule using correct template
3. Verify Locale: Template exists for customer's language
4. Test with Real Data: Use preview with actual booking data

Duplicate Notifications

1. Check Rule Overlap: Multiple rules for same event
2. Review Triggers: Different triggers for same purpose
3. Verify Scanner: Date scanner runs deduplication

Configuration

Environment Variables

Variable	Default	Description
NOTIFICATION_WORKER_ENABLED	true	Enable notification worker
NOTIFICATION_WORKER_INTERVAL_MS	60000	Scan interval (ms)
NOTIFICATION_WORKER_BATCH_SIZE	50	Notifications per batch
BOOKING_DATE_SCANNER_ENABLED	true	Enable date-based scanner
BOOKING_DATE_SCANNER_HOUR	2	Hour to run scanner (0-23)
BOOKING_DATE_SCANNER_WINDOW_DAYS	14	Days ahead to scan

Next Steps

• Configure Email Provider in your environment
• Review Operations for monitoring notification delivery
• Check Reports for notification analytics