Alerts

Overview

Alerts is a core navigation tab (4th item in the main navbar: Home, Tasks, Calendar, Alerts). Alerts are urgent but don't have a schedule—they appear contextually when needed. The Butler centralizes all alerts from all Butlers in one unified interface. All Butlers can create alerts through the Smart Alert Engine, and users can view, filter, and manage them all from the Alerts tab.

Create Alerts

Create alerts through The Butler's Smart Alert Engine. Alerts are different from Calendar entries (which are scheduled) and Tasks (which can be done within the day but don't require a schedule).

Basic Alert

// Create alert
const alert = await window.lifeButler.alerts.create({
  title: 'Medication Overdue',
  body: 'Luna's monthly flea treatment is overdue',
  priority: 'medium',
  category: 'health',
  butlerId: 'pet-butler',
  action: {
    type: 'navigate',
    path: '/butlers/pet-care/medications',
    params: { petId: 'pet-123' }
  }
});

Alert with Actions

// Create alert with action buttons
const alert = await window.lifeButler.alerts.create({
  title: 'Medication Overdue',
  body: 'Luna's monthly flea treatment is overdue',
  priority: 'high',
  category: 'health',
  butlerId: 'pet-butler',
  actions: [
    {
      id: 'mark-taken',
      label: 'Mark Taken',
      action: async () => {
        await markMedicationTaken('med-123');
        await window.lifeButler.alerts.dismiss(alert.id);
      }
    },
    {
      id: 'snooze',
      label: 'Snooze 15 min',
      action: async () => {
        await window.lifeButler.alerts.snooze(alert.id, 15 * 60 * 1000);
      }
    }
  ],
  action: {
    type: 'navigate',
    path: '/butlers/pet-care/medications',
    params: { petId: 'pet-123' }
  }
});

Alert Priorities

Alerts support different priority levels that determine how they are displayed and delivered.

• Low: Silent, appears in alert center only. Use for informational alerts that don't require immediate attention.
• Medium: Standard alert with sound. Use for alerts that need attention but aren't urgent.
• High: Prominent display, may break through Do Not Disturb. Use for urgent alerts that need immediate attention.
• Critical: Always delivered, bypasses all settings (requires special permission). Use only for critical alerts that must be seen immediately.

// Create high-priority alert
await window.lifeButler.alerts.create({
  title: 'Bill Payment Due Today',
  body: 'Your rent payment is due today',
  priority: 'high',
  category: 'finance',
  butlerId: 'rent-butler'
});

Alert Actions

Add action buttons to alerts so users can take action directly from the alert. Handle user interactions through the onAlert hook.

Handle Alert Actions

// Listen for alert actions
window.lifeButler.onAlert((alert, actionId) => {
  if (alert.butlerId === 'my-butler') {
    if (actionId === 'mark-taken') {
      handleMarkTaken(alert);
    } else if (actionId === 'snooze') {
      handleSnooze(alert);
    }
  }
});

// Or handle actions when creating alert
const alert = await window.lifeButler.alerts.create({
  title: 'Medication Overdue',
  body: 'Luna's monthly flea treatment is overdue',
  priority: 'medium',
  actions: [
    {
      id: 'mark-taken',
      label: 'Mark Taken',
      action: async () => {
        await markMedicationTaken('med-123');
        await window.lifeButler.alerts.dismiss(alert.id);
      }
    }
  ]
});

Manage Alerts

Update, dismiss, or snooze alerts as needed.

// Dismiss alert
await window.lifeButler.alerts.dismiss(alertId);

// Snooze alert (show again after delay)
await window.lifeButler.alerts.snooze(alertId, delayMs);

// Update alert
await window.lifeButler.alerts.update(alertId, {
  title: 'Updated Title',
  body: 'Updated body text'
});

// Get alerts created by your Butler
const alerts = await window.lifeButler.alerts.getByButler('my-butler');

User Preferences

Users can control alert preferences per Butler and category through The Butler's settings. Your Butler should respect these preferences and only create alerts when appropriate.

// Check if alerts are enabled for your Butler
const preferences = await window.lifeButler.getAlertPreferences('my-butler');
// Returns: { enabled: true, categories: { health: true, finance: false } }

// Only create alert if enabled
if (preferences.enabled && preferences.categories[category]) {
  await window.lifeButler.alerts.create({ ... });
}

Requirements

• Use appropriate priority: Use the right priority level for each alert. Don't use high or critical priority for non-urgent alerts.
• Provide actions: Add action buttons to alerts when users can take action directly from the alert.
• Respect preferences: Check user preferences before creating alerts and respect their choices.
• Handle dismissals: Handle alert dismissals and update your Butler's state accordingly.
• Use categories: Use appropriate categories for alerts so users can filter and manage them effectively.