# Smart Filters Guide
The Nostr Notifier now includes intelligent filtering to reduce notification spam and improve relevance.
## 🎛️ Available Filters
### 1. **Rate Limiting**
Prevents notification floods by limiting messages per minute.
- **Default:** 10 notifications per minute
- **Config:** `rate_limit_per_minute` in `config.py`
- **Method:** `notifier.set_rate_limit(20)`
### 2. **Thread Deduplication**
Only notifies for the first mention/reply in a thread, preventing spam from long discussions.
- **Default:** Enabled
- **Config:** `thread_dedup: True` in `config.py`
- **How it works:** Tracks root event IDs and only sends notification for first event in each thread
### 3. **Engagement Threshold**
Only notify for posts that reach a minimum level of engagement (reactions + reposts).
- **Default:** 0 (notify all)
- **Config:** `engagement_threshold` in `config.py`
- **Method:** `notifier.set_engagement_threshold(5)`
- **Use case:** Only get notified for popular posts
### 4. **Trusted Users (Whitelist)**
Always notify for specific users, regardless of other filters.
- **Config:** `trusted_users: ["npub1...", "npub2..."]` in `config.py`
- **Method:** `notifier.add_trusted_user("npub1...")`
- **Use case:** Important contacts you never want to miss
### 5. **Blocked Users (Blacklist)**
Never notify for specific users.
- **Config:** `blocked_users: ["npub1...", "npub2..."]` in `config.py`
- **Method:** `notifier.add_blocked_user("npub1...")`
- **Use case:** Filter out spam accounts or noisy users
### 6. **User Engagement Tracking**
Tracks how often each user interacts with you. Useful for identifying important contacts.
- **Stats:** View with `notifier.get_stats()`
- **Use case:** Identify your most engaged followers
## 📝 Configuration
Edit `config.py`:
```python
SMART_FILTERS = {
"rate_limit_per_minute": 10, # Max notifications per minute
"engagement_threshold": 0, # 0 = all, 5 = only 5+ engagement
"thread_dedup": True, # Avoid thread spam
"trusted_users": [], # Always notify for these npubs
"blocked_users": [], # Never notify for these npubs
}
```
## 📊 Statistics
View current stats in logs or via `notifier.get_stats()`:
```python
{
"events_seen": 1234,
"threads_cached": 567,
"profiles_cached": 890,
"users_tracked": 123,
"trusted_users": 5,
"blocked_users": 2,
"rate_limit": 10,
"engagement_threshold": 0,
}
```
## 🔧 Runtime Configuration
You can modify filters at runtime by extending the bot with a simple HTTP API or interactive commands.
## 💡 Recommended Settings
### For Active Users (lots of mentions):
```python
SMART_FILTERS = {
"rate_limit_per_minute": 5,
"engagement_threshold": 2,
"thread_dedup": True,
}
```
### For Important Notifications Only:
```python
SMART_FILTERS = {
"rate_limit_per_minute": 3,
"engagement_threshold": 5,
"thread_dedup": True,
"trusted_users": ["npub1important..."],
}
```
### For Quiet Mode:
```python
SMART_FILTERS = {
"rate_limit_per_minute": 1,
"engagement_threshold": 10,
"thread_dedup": True,
}
```
## 🚀 Restarting with New Settings
```bash
cd ~/nostr-notifier
pkill -f notifier.py
TELEGRAM_BOT_TOKEN='your-token' .venv/bin/python notifier.py
```