Skip to content

Notification Settings

Complete guide to customizing notification behavior including booking reminder timings and message templates.

Overview

The notification settings system allows tenants to customize:

  • Booking Reminders - Configure when to send appointment reminders (up to 5 timings)
  • Message Templates - Customize content for push, email, and WhatsApp notifications
  • Feature Toggles - Enable/disable custom settings vs system defaults

Key Concepts:

  • Reminder Timing = When to send booking reminders relative to appointment time
  • Template Override = Custom message content per notification type and channel
  • Feature Flags = Toggle between custom and system default settings
  • Jinja2 Templates = Use variables like {{ customer_name }} for personalization

Notification System Documentation

The notification system spans multiple documentation pages:

Document Purpose When to Use
This Page Customize templates & reminder timings Configuring tenant-specific notification preferences
Notification Management API for sending/scheduling notifications Implementing notification sending in your app
Appointment Management Auto-triggered booking notifications Understanding automatic appointment notifications

How They Work Together:

  1. Settings (this page) define what templates look like and when reminders are sent
  2. Management (notification-management.md) provides the API to send notifications manually
  3. Appointments (appointment-management.md) automatically trigger notifications using these settings

What's Customizable vs. Fixed

Aspect Customizable? Notes
Reminder Timings Yes Up to 5 reminders per booking
Message Content Yes Push, Email, WhatsApp templates
Template Variables No Predefined per notification type
Sender Identity No Always from Reserva platform
Channel Availability No Based on subscription tier
Channel Quotas No Based on subscription tier

Subscription Tier Limits

While notification settings customization is available to all plans, the actual notification delivery is still subject to your subscription tier's channel quotas. See Notification Management for quota details.

Get Notification Settings

Retrieve current notification customization settings.

Endpoint

GET /api/v1/notifications/settings

Authentication: Required (JWT token)

Access: TENANT_ADMIN (full access), OUTLET_MANAGER (read-only)

Response

{
  "id": "507f1f77bcf86cd799439011",
  "tenant_id": "507f1f77bcf86cd799439012",
  "booking_reminders": [
    {
      "value": 24,
      "unit": "hours",
      "channels": ["push", "whatsapp", "email"]
    },
    {
      "value": 2,
      "unit": "hours",
      "channels": ["push", "whatsapp"]
    }
  ],
  "template_overrides": {
    "booking_confirmation": {
      "push_title": "Booking Confirmed!",
      "push_body": "Your appointment at {{ tenant_name }} is confirmed.",
      "email_subject": "Your {{ tenant_name }} Appointment Confirmation",
      "email_body": "Dear {{ customer_name }}, ...",
      "whatsapp_message": "Hi {{ customer_name }}! Your booking is confirmed."
    }
  },
  "use_custom_templates": true,
  "use_custom_reminders": true,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Response Fields:

Field Description
booking_reminders List of reminder timing configurations
template_overrides Custom templates by notification type
use_custom_templates Whether custom templates are active
use_custom_reminders Whether custom reminder timing is active

Notes:

  • Creates default settings automatically on first access
  • Default: 1 reminder at 24 hours before via push, WhatsApp, and email

Update Notification Settings

Update all notification customization settings at once.

Endpoint

PUT /api/v1/notifications/settings

Authentication: Required (JWT token)

Access: TENANT_ADMIN only

Request Body

{
  "booking_reminders": [
    {"value": 24, "unit": "hours", "channels": ["push", "whatsapp", "email"]},
    {"value": 2, "unit": "hours", "channels": ["push", "whatsapp"]},
    {"value": 30, "unit": "minutes", "channels": ["push"]}
  ],
  "template_overrides": {
    "booking_confirmation": {
      "push_title": "Booking Confirmed!",
      "push_body": "Hi {{ customer_name }}, your appointment is confirmed!",
      "whatsapp_message": "Hi {{ customer_name }}! Your booking at {{ tenant_name }} is confirmed for {{ appointment_date }} at {{ appointment_time }}."
    }
  },
  "use_custom_templates": true,
  "use_custom_reminders": true
}

Parameters:

Parameter Type Required Description
booking_reminders array No Reminder configurations (max 5)
template_overrides object No Custom templates by notification type
use_custom_templates boolean No Enable/disable custom templates
use_custom_reminders boolean No Enable/disable custom reminders

Response

Returns updated TenantNotificationSettingsOut (same as GET response).

Update Booking Reminders

Update only the booking reminder timing configuration.

Endpoint

PUT /api/v1/notifications/settings/reminders

Authentication: Required (JWT token)

Access: TENANT_ADMIN only

Request Body

{
  "reminders": [
    {"value": 24, "unit": "hours", "channels": ["push", "whatsapp", "email"]},
    {"value": 2, "unit": "hours", "channels": ["push", "whatsapp"]},
    {"value": 30, "unit": "minutes", "channels": ["push"]}
  ],
  "enable_custom": true
}

Parameters:

Parameter Type Required Description
reminders array Yes Reminder configurations (max 5)
enable_custom boolean No Also enable use_custom_reminders (default: true)

Reminder Timing Schema

{
  "value": 24,
  "unit": "hours",
  "channels": ["push", "whatsapp", "email"]
}
Field Type Constraints Description
value integer 1-168 Timing value
unit string minutes, hours, days Time unit
channels array 1-3 items Delivery channels

Timing Constraints:

  • Maximum value: 168 (7 days when unit is hours)
  • Maximum 5 reminder timings per tenant
  • Each reminder can have 1-3 channels

Example Configurations

Standard Business: 

{
  "reminders": [
    {"value": 24, "unit": "hours", "channels": ["push", "whatsapp", "email"]},
    {"value": 1, "unit": "hours", "channels": ["push"]}
  ]
}

High-Touch Service: 

{
  "reminders": [
    {"value": 3, "unit": "days", "channels": ["email"]},
    {"value": 24, "unit": "hours", "channels": ["push", "whatsapp"]},
    {"value": 2, "unit": "hours", "channels": ["push", "whatsapp"]},
    {"value": 30, "unit": "minutes", "channels": ["push"]}
  ]
}

Update Template Override

Update the message template for a specific notification type.

Endpoint

PUT /api/v1/notifications/settings/templates/{notification_type}

Authentication: Required (JWT token)

Access: TENANT_ADMIN only

Path Parameters

Parameter Description Example
notification_type Type of notification to customize booking_confirmation

Query Parameters

Parameter Type Default Description
enable_custom boolean true Also enable use_custom_templates

Request Body

{
  "push_title": "Booking Confirmed!",
  "push_body": "Hi {{ customer_name }}, your appointment is confirmed!",
  "email_subject": "Your {{ tenant_name }} Booking Confirmation",
  "email_body": "Dear {{ customer_name }},\n\nYour appointment is confirmed for {{ appointment_date }} at {{ appointment_time }}.\n\nSee you at {{ outlet_name }}!",
  "whatsapp_message": "Hi {{ customer_name }}! Your booking at {{ tenant_name }} is confirmed.\n\nDate: {{ appointment_date }}\nTime: {{ appointment_time }}\nLocation: {{ outlet_name }}"
}

Template Override Fields:

Field Max Length Description
push_title 100 chars Push notification title
push_body 500 chars Push notification body
email_subject 200 chars Email subject line
email_body 10,000 chars Email body (HTML or text)
whatsapp_message 4,096 chars WhatsApp message

All fields are optional. Only provide fields you want to customize.

Supported Notification Types

Type Description
booking_confirmation Appointment booking confirmed
booking_reminder Upcoming appointment reminder
booking_cancelled Appointment cancellation notice
booking_rescheduled Appointment time change notice
payment_receipt Payment confirmation
welcome New customer welcome message

Template Variables

Get Available Variables

Retrieve available template variables for a notification type.

Endpoint

GET /api/v1/notifications/settings/variables/{notification_type}

Authentication: Required (JWT token)

Access: TENANT_ADMIN, OUTLET_MANAGER

Response

{
  "notification_type": "booking_confirmation",
  "variables": [
    "customer_name",
    "tenant_name",
    "service_names",
    "appointment_date",
    "appointment_time",
    "outlet_name",
    "outlet_address",
    "staff_name",
    "total_amount",
    "booking_reference"
  ],
  "sample_data": {
    "customer_name": "John Doe",
    "tenant_name": "Glow Salon",
    "service_names": "Haircut, Styling",
    "appointment_date": "Jan 15, 2025",
    "appointment_time": "10:00 AM",
    "outlet_name": "Glow Salon - Kemang",
    "outlet_address": "Jl. Kemang Raya No. 10",
    "staff_name": "Sarah",
    "total_amount": "Rp 150.000",
    "booking_reference": "BK-2025-001"
  }
}

Variables by Notification Type

Type Variables
booking_confirmation customer_name, tenant_name, service_names, appointment_date, appointment_time, outlet_name, outlet_address, staff_name, total_amount, booking_reference
booking_reminder customer_name, tenant_name, service_names, appointment_date, appointment_time, outlet_name, outlet_address, staff_name
booking_cancelled customer_name, tenant_name, service_names, appointment_date, appointment_time, cancellation_reason, refund_amount
booking_rescheduled customer_name, tenant_name, old_date, old_time, new_date, new_time, outlet_name, staff_name
payment_receipt customer_name, tenant_name, invoice_number, amount, payment_method, service_names, payment_date
welcome customer_name, tenant_name

Preview Template

Preview how a notification will look with sample data.

Endpoint

GET /api/v1/notifications/settings/preview/{notification_type}

Authentication: Required (JWT token)

Access: TENANT_ADMIN, OUTLET_MANAGER

Path Parameters

Parameter Description Example
notification_type Type of notification booking_confirmation

Query Parameters

Parameter Type Required Description
channel string Yes Channel to preview: push, email, whatsapp

Response

{
  "notification_type": "booking_confirmation",
  "channel": "push",
  "rendered_title": "Booking Confirmed!",
  "rendered_body": "Hi John Doe, your appointment at Glow Salon is confirmed for Jan 15, 2025 at 10:00 AM.",
  "rendered_html": null,
  "sample_data": {
    "customer_name": "John Doe",
    "tenant_name": "Glow Salon",
    "appointment_date": "Jan 15, 2025",
    "appointment_time": "10:00 AM"
  },
  "uses_custom_template": true
}

Response Fields:

Field Description
rendered_title Rendered title (push/email only)
rendered_body Rendered body text
rendered_html Rendered HTML (email only)
sample_data Data used for rendering
uses_custom_template Whether custom template was applied

Toggle Features

Toggle Custom Templates

Enable or disable custom template usage.

PUT /api/v1/notifications/settings/toggle/custom-templates?enabled=true

Access: TENANT_ADMIN only

Toggle Custom Reminders

Enable or disable custom reminder timing.

PUT /api/v1/notifications/settings/toggle/custom-reminders?enabled=true

Access: TENANT_ADMIN only

Query Parameters:

Parameter Type Required Description
enabled boolean Yes Enable or disable the feature

Reset to Defaults

Reset all notification settings to system defaults.

Endpoint

POST /api/v1/notifications/settings/reset

Authentication: Required (JWT token)

Access: TENANT_ADMIN only

Response

Returns reset TenantNotificationSettingsOut with:

  • Default reminder: 24 hours before via push, WhatsApp, email
  • Empty template overrides
  • use_custom_templates: false
  • use_custom_reminders: false

Irreversible Action

This action cannot be undone. All customizations will be permanently lost.

Jinja2 Template Syntax

Templates use Jinja2 syntax for dynamic content:

Variable Substitution

Hi {{ customer_name }}, your booking is confirmed!

Conditional Content

{% if refund_amount %}
Refund amount: {{ refund_amount }}
{% endif %}

Default Values

Hello {{ customer_name | default('Valued Customer') }}!

Example Templates

Push Notification: 

Title: Appointment Reminder
Body: {{ customer_name }}, your {{ service_names }} appointment is in 2 hours at {{ outlet_name }}.

Email: 

Subject: Your {{ tenant_name }} Appointment Confirmation

<h1>Booking Confirmed!</h1>
<p>Dear {{ customer_name }},</p>
<p>Your appointment has been confirmed:</p>
<ul>
  <li><strong>Services:</strong> {{ service_names }}</li>
  <li><strong>Date:</strong> {{ appointment_date }}</li>
  <li><strong>Time:</strong> {{ appointment_time }}</li>
  <li><strong>Location:</strong> {{ outlet_name }}, {{ outlet_address }}</li>
  <li><strong>Stylist:</strong> {{ staff_name }}</li>
</ul>
<p>Reference: {{ booking_reference }}</p>

WhatsApp: 

Halo {{ customer_name }}!

Booking Anda telah dikonfirmasi:
- Layanan: {{ service_names }}
- Tanggal: {{ appointment_date }}
- Jam: {{ appointment_time }}
- Lokasi: {{ outlet_name }}

Sampai jumpa!

Best Practices

For Reminder Timing

DO:

  • Configure at least one reminder 24 hours before
  • Use push for last-minute reminders (30 min - 2 hours)
  • Use email for advance notices (1-3 days)
  • Limit WhatsApp to 2-3 reminders to avoid spam perception

DON'T:

  • Send more than 3 reminders via WhatsApp
  • Schedule reminders too close together (space by at least 2 hours)
  • Use all channels for every reminder (causes notification fatigue)

For Template Customization

DO:

  • Keep push notifications short (under 100 characters for body)
  • Include essential info: date, time, location
  • Preview templates before enabling
  • Test on all channels after customization

DON'T:

  • Use unsupported variables (causes rendering errors)
  • Create overly long WhatsApp messages
  • Forget to include booking reference for confirmations
  • Use complex Jinja2 logic (keep templates simple)

Frontend UI Suggestions

Settings Dashboard

+------------------------------------------------------------------+
|  NOTIFICATION SETTINGS                                            |
+------------------------------------------------------------------+
|                                                                   |
|  QUICK STATUS                                                     |
|  +---------------------------+  +---------------------------+     |
|  | Custom Templates          |  | Custom Reminders          |     |
|  | [====ON====] [OFF]        |  | [====ON====] [OFF]        |     |
|  +---------------------------+  +---------------------------+     |
|                                                                   |
|  TABS: [Reminders] [Templates] [Preview]                          |
|                                                                   |
+------------------------------------------------------------------+

Reminder Configuration

+------------------------------------------------------------------+
|  BOOKING REMINDERS                                    [+ Add]     |
+------------------------------------------------------------------+
|                                                                   |
|  | Timing              | Channels                    | Actions   |
|  |---------------------|-----------------------------|-----------|
|  | 24 hours before     | Push, WhatsApp, Email      | [Edit][X] |
|  | 2 hours before      | Push, WhatsApp             | [Edit][X] |
|  | 30 minutes before   | Push                        | [Edit][X] |
|  |---------------------|-----------------------------|-----------|
|                                                                   |
|  Maximum 5 reminders allowed. You have 3 configured.              |
|                                                                   |
+------------------------------------------------------------------+

Add/Edit Reminder Modal

+------------------------------------------------------------------+
|  EDIT REMINDER                                               [X]  |
+------------------------------------------------------------------+
|                                                                   |
|  Timing                                                           |
|  +----------------------+  +-------------------+                  |
|  | Value: [  24  ]      |  | Unit: [hours ▼]   |                  |
|  +----------------------+  +-------------------+                  |
|                                                                   |
|  Channels                                                         |
|  [✓] Push    [✓] WhatsApp    [ ] Email                           |
|                                                                   |
|  Preview: "Send reminder 24 hours before appointment              |
|           via Push and WhatsApp"                                  |
|                                                                   |
|                                        [Cancel] [Save Changes]    |
|                                                                   |
+------------------------------------------------------------------+

Template Editor

+------------------------------------------------------------------+
|  TEMPLATE EDITOR                                                  |
+------------------------------------------------------------------+
|  Type: [Booking Confirmation ▼]    Channel: [Push ▼]              |
+------------------------------------------------------------------+
|                                                                   |
|  AVAILABLE VARIABLES (click to insert)                            |
|  [customer_name] [tenant_name] [service_names] [appointment_date] |
|  [appointment_time] [outlet_name] [staff_name] [total_amount]     |
|                                                                   |
|  TITLE                                                            |
|  +---------------------------------------------------------------+|
|  | Booking Confirmed!                                            ||
|  +---------------------------------------------------------------+|
|                                                                   |
|  BODY                                                             |
|  +---------------------------------------------------------------+|
|  | Hi {{ customer_name }}, your appointment at {{ tenant_name }} ||
|  | is confirmed for {{ appointment_date }} at                    ||
|  | {{ appointment_time }}.                                       ||
|  +---------------------------------------------------------------+|
|                                                                   |
|  [Preview]                           [Reset to Default] [Save]    |
|                                                                   |
+------------------------------------------------------------------+

Template Preview

+------------------------------------------------------------------+
|  TEMPLATE PREVIEW                                            [X]  |
+------------------------------------------------------------------+
|  Type: booking_confirmation    Channel: Push                      |
+------------------------------------------------------------------+
|                                                                   |
|  PREVIEW                                                          |
|  +---------------------------------------------------------------+|
|  |  +------------------------------------------------------+     ||
|  |  | Booking Confirmed!                                    |     ||
|  |  | Hi John Doe, your appointment at Glow Salon is       |     ||
|  |  | confirmed for Jan 15, 2025 at 10:00 AM.              |     ||
|  |  +------------------------------------------------------+     ||
|  +---------------------------------------------------------------+|
|                                                                   |
|  SAMPLE DATA USED                                                 |
|  +---------------------------------------------------------------+|
|  | customer_name: "John Doe"                                     ||
|  | tenant_name: "Glow Salon"                                     ||
|  | appointment_date: "Jan 15, 2025"                              ||
|  | appointment_time: "10:00 AM"                                  ||
|  +---------------------------------------------------------------+|
|                                                                   |
|  [✓] Using Custom Template                                        |
|                                                                   |
|                                             [Close] [Edit Template]|
|                                                                   |
+------------------------------------------------------------------+

Channel Preview Tabs

+------------------------------------------------------------------+
|  PREVIEW ALL CHANNELS                                             |
+------------------------------------------------------------------+
|  Type: [Booking Confirmation ▼]                                   |
+------------------------------------------------------------------+
|                                                                   |
|  [Push] [Email] [WhatsApp]                                        |
|  ------                                                           |
|                                                                   |
|  +---------------------------------------------------------------+|
|  |  PUSH NOTIFICATION                                            ||
|  |  +---------------------------------------------------+        ||
|  |  | Booking Confirmed!                                 |        ||
|  |  | Hi John, your appointment is confirmed for Jan 15. |        ||
|  |  +---------------------------------------------------+        ||
|  +---------------------------------------------------------------+|
|                                                                   |
+------------------------------------------------------------------+

Reset Confirmation Dialog

+------------------------------------------------------------------+
|  RESET TO DEFAULTS                                           [X]  |
+------------------------------------------------------------------+
|                                                                   |
|  [!] Warning: This action cannot be undone                        |
|                                                                   |
|  Resetting will:                                                  |
|  - Remove all custom templates                                    |
|  - Reset reminders to default (24 hours)                          |
|  - Disable custom templates and reminders                         |
|                                                                   |
|  Are you sure you want to continue?                               |
|                                                                   |
|                                        [Cancel] [Reset to Defaults]|
|                                                                   |
+------------------------------------------------------------------+

Settings Status Indicators

State Indicator Color
Custom Templates ON Toggle right Green
Custom Templates OFF Toggle left Gray
Custom Reminders ON Toggle right Green
Custom Reminders OFF Toggle left Gray
Template Modified Badge Blue
Using System Default Badge Gray

Error Handling

Common Errors

Error Status Code Cause Solution
Insufficient permissions 403 Not TENANT_ADMIN Only TENANT_ADMIN can modify settings
Maximum 5 reminders allowed 422 Too many reminders Remove some reminders
Template not found 404 Invalid notification type Use supported notification types
Failed to preview template 500 Jinja2 rendering error Check template syntax

Error Response Format

{
  "detail": "Only TENANT_ADMIN can modify notification settings"
}

API Reference Summary

Endpoint Method Purpose Access
/notifications/settings GET Get current settings TENANT_ADMIN, OUTLET_MANAGER
/notifications/settings PUT Update all settings TENANT_ADMIN
/notifications/settings/reminders PUT Update reminders only TENANT_ADMIN
/notifications/settings/templates/{type} PUT Update single template TENANT_ADMIN
/notifications/settings/preview/{type} GET Preview template TENANT_ADMIN, OUTLET_MANAGER
/notifications/settings/variables/{type} GET Get available variables TENANT_ADMIN, OUTLET_MANAGER
/notifications/settings/reset POST Reset to defaults TENANT_ADMIN
/notifications/settings/toggle/custom-templates PUT Toggle templates TENANT_ADMIN
/notifications/settings/toggle/custom-reminders PUT Toggle reminders TENANT_ADMIN

Notification System

Document Description
Notification Management Send/schedule notifications, view usage stats, notification history
Appointment Management - Auto Notifications How appointment actions trigger automatic notifications

Integration

Next Steps:

  1. View current settings: GET /notifications/settings
  2. Configure reminder timings: PUT /notifications/settings/reminders
  3. Get available variables: GET /notifications/settings/variables/{type}
  4. Customize templates: PUT /notifications/settings/templates/{type}
  5. Preview changes: GET /notifications/settings/preview/{type}?channel=push
  6. Enable customizations: PUT /notifications/settings/toggle/custom-templates?enabled=true