Skip to content

Notification System Quick Start

Get started with sending notifications in under 5 minutes using our ultra-simple API.

🚀 The Simplest Way

import { notifications } from '@/util/notifications/ultra-simple'

// Send email notification
const result = await notifications.email('case-received-customer', 'user@example.com', {
  caseNumber: 'CW-2025-001',
  customerName: 'John Doe',
  issueType: 'Technical Support'
})

console.log(result) // { success: true, message: "Email sent to user@example.com" }

That's it! One line to send a template-driven email notification.

📋 Basic Operations

Send Email Notifications

// Customer notifications
await notifications.email('case-received-customer', customer.email, {
  caseNumber: case.caseNumber,
  customerName: case.name,
  issueType: case.issueType
})

// Internal staff notifications  
await notifications.email('case-assigned-staff', staff.email, {
  caseNumber: case.caseNumber,
  customerName: case.name,
  staffName: staff.name,
  urgency: case.urgency
})

Send SMS Notifications

// Simple SMS
await notifications.sms('+1234567890', 'Your case CW-2025-001 has been updated.')

// Template-based SMS (if you have SMS templates)
await notifications.sms(customer.phone, 
  `Hello ${customer.name}, your case ${case.caseNumber} has been received.`
)

Send Webhooks

// External system notifications
await notifications.webhook('https://external-system.com/webhook', {
  event: 'case_created',
  caseNumber: case.caseNumber,
  timestamp: new Date().toISOString()
})

🧪 Testing Templates

Before sending notifications, test your templates:

// Test a template with sample data
const test = await notifications.test('case-escalated-customer', {
  caseNumber: 'CW-2025-001',
  customerName: 'John Doe',
  originalUrgency: 'MEDIUM',
  newUrgency: 'HIGH',
  escalationReason: 'Customer request'
})

if (test.success) {
  console.log('Subject:', test.data.subject)
  console.log('Content preview:', test.data.content.substring(0, 100))
} else {
  console.error('Template test failed:', test.error)
}

📚 Available Templates

Get a list of all available templates:

const templates = notifications.templates()
console.log(templates)

Output: 

[
  { id: 'case-received-customer', name: 'Case Received - Customer', category: 'customer' },
  { id: 'case-assigned-staff', name: 'Case Assigned - Staff', category: 'internal' },
  { id: 'case-escalated-customer', name: 'Case Escalated - Customer', category: 'customer' },
  // ... more templates
]

🔍 Template Information

Get details about a specific template:

const info = notifications.info('case-received-customer')
console.log(info)

Output: 

{
  success: true,
  data: {
    id: 'case-received-customer',
    name: 'Case Received - Customer Notification',
    category: 'customer',
    required: ['caseNumber', 'customerName', 'issueType'],
    optional: ['urgency', 'estimatedResolution']
  }
}

⚡ Real-world Examples

In a Support Case Controller

import { notifications } from '@/util/notifications/ultra-simple'

export const createSupportCaseController = async (req, res) => {
  try {
    // Create the case in database
    const supportCase = await db.supportCase.create({ data: caseData })

    // Send customer notification
    const customerNotification = await notifications.email(
      'case-received-customer', 
      supportCase.email, 
      {
        caseNumber: supportCase.caseNumber,
        customerName: supportCase.name,
        issueType: supportCase.issueType,
        urgency: supportCase.urgency,
        estimatedResolution: getEstimatedResolution(supportCase.urgency)
      }
    )

    // Send internal staff notification
    const staffNotification = await notifications.email(
      'case-received-staff',
      'support@cyferwall.com',
      {
        caseNumber: supportCase.caseNumber,
        customerName: supportCase.name,
        customerEmail: supportCase.email,
        issueType: supportCase.issueType,
        urgency: supportCase.urgency,
        priorityScore: getPriorityScore(supportCase)
      }
    )

    // Log results
    if (!customerNotification.success) {
      console.error('Customer notification failed:', customerNotification.error)
    }
    if (!staffNotification.success) {
      console.error('Staff notification failed:', staffNotification.error)
    }

    res.json({ success: true, caseNumber: supportCase.caseNumber })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
}

Batch Notifications

// Send notifications to multiple recipients
const notifyMultipleStaff = async (caseData, staffList) => {
  const results = await Promise.all(
    staffList.map(staff => 
      notifications.email('case-urgent-staff', staff.email, {
        ...caseData,
        staffName: staff.name,
        department: staff.department
      })
    )
  )

  const failedNotifications = results.filter(r => !r.success)
  if (failedNotifications.length > 0) {
    console.error(`${failedNotifications.length} staff notifications failed`)
  }
}

🔧 Error Handling

The notification service returns consistent results:

const result = await notifications.email('template-id', 'user@example.com', data)

if (result.success) {
  console.log('✅', result.message)
} else {
  console.error('❌', result.error)
  // Handle error (retry, log, alert, etc.)
}

Common error scenarios: - Template not found: Invalid template ID - Missing required variables: Required template variables not provided - Service not ready: Notification service failed to initialize - Rendering error: Template syntax errors or invalid data

🎯 Best Practices

1. Always Check Results

const result = await notifications.email(templateId, email, data)
if (!result.success) {
  // Log error, retry, or handle gracefully
  logger.error(`Notification failed: ${result.error}`)
}

2. Use Template Testing in Development

// Test before sending in production
if (process.env.NODE_ENV === 'development') {
  const test = await notifications.test(templateId, data)
  console.log('Template test:', test)
}

await notifications.email(templateId, email, data)

3. Provide All Required Variables

// Check template requirements first
const info = notifications.info(templateId)
console.log('Required variables:', info.data?.required)

// Ensure all required variables are provided
const data = {
  caseNumber: case.caseNumber,
  customerName: case.name,
  // ... include all required variables
}

🚀 Next Steps

  1. Template Management - Learn about template structure and creation
  2. Integration Guide - Integrate notifications throughout your application
  3. API Reference - Complete API documentation
  4. Troubleshooting - Common issues and solutions

Ready to send your first notification? Try the examples above in your development environment!