alfred-mobile/NOTIFICATIONS.md

# Background Notifications

## Overview

Alfred Mobile now supports **background notifications** so you can receive alerts when Alfred finishes processing work while the app is in the background.

## Features

✅ **Background alerts** - Get notified when Alfred responds, even when the app is minimized  
✅ **Auto-permission request** - App asks for notification permission on first launch (Android 13+)  
✅ **Smart notifications** - Only sends notifications when app is backgrounded (no spam when you're actively chatting)  
✅ **Tap to open** - Tap notification to jump back to the conversation  

## How It Works

### Foreground (App Open)
- Messages appear in chat instantly
- TTS plays if "Voice On" is enabled
- No notifications (you're already looking at the app)

### Background (App Minimized)
- Alfred's responses trigger a notification
- Notification shows message preview
- Tap to open app and continue conversation

## Permission

### Android 13+ (API 33+)
- **POST_NOTIFICATIONS** permission required
- App requests permission ~2 seconds after first launch
- If denied, you won't get background notifications (but everything else works)

### Android 12 and below
- No permission needed
- Notifications work automatically

## Use Cases

### Example 1: Long Processing
1. Ask Alfred a complex question
2. Switch to another app while waiting
3. Get notification when Alfred responds
4. Tap notification to see the answer

### Example 2: Background Work
1. Tell Alfred to "remind me in 10 minutes"
2. Close the app
3. Get notification when reminder fires
4. Tap to open conversation

### Example 3: Multitasking
1. Start a voice conversation
2. Switch to check email while Alfred processes
3. Get notified when Alfred responds
4. Switch back to continue

## Wake Word Model Loading

When you enable wake word mode for the first time:
1. **Toast notification**: "Loading wake word model..."
2. Model unpacks from assets (~39MB, takes 5-10 seconds)
3. **Toast notification**: "Wake word ready!"
4. You can now use "Hey Alfred" or "Alfred" to trigger voice input

## Technical Details

### Notification Channel
- **ID**: `alfred_messages`
- **Name**: "Alfred Messages"
- **Importance**: Default (makes sound + shows on lock screen)
- **Vibration**: Enabled
- **Lights**: Enabled

### Notification Content
- **Title**: "Alfred"
- **Message**: Full text of Alfred's response
- **Style**: BigTextStyle (expands to show full message)
- **Action**: Tap to open app
- **Auto-cancel**: Yes (dismisses after tap)

### Background Detection
Uses Android lifecycle observers to track when app moves to background:
- `ON_RESUME` → Foreground (no notifications)
- `ON_PAUSE` → Background (send notifications)

### Implementation
- **NotificationHelper.kt**: Manages notification channel and sending
- **MainActivity.kt**: Initializes notification channel on startup
- **MainScreen.kt**: Tracks foreground/background state, sends notifications

## Privacy

- Notifications only appear on your device
- No data sent to external services
- Same privacy as in-app messages

## Future Enhancements

Potential improvements:
- [ ] Notification actions (reply directly, dismiss, etc.)
- [ ] Group conversations into single notification
- [ ] Custom notification sounds
- [ ] Notification priority/importance settings
- [ ] Do Not Disturb integration
- [ ] Notification history/log

## Related Files

- **Notification logic**: `app/src/main/java/com/openclaw/alfred/notifications/NotificationHelper.kt`
- **Channel setup**: `app/src/main/java/com/openclaw/alfred/MainActivity.kt`
- **Background detection**: `app/src/main/java/com/openclaw/alfred/ui/screens/MainScreen.kt`
- **Permissions**: `app/src/main/AndroidManifest.xml`

---

**Stay connected with Alfred, even when multitasking!** 🔔