# 📱 NTFY Quick Reference

*Quick reference guide for NTFY notification system usage*

## Basic Usage

### Send Simple Message
```bash
curl -d "Hello World" https://ntfy.vish.gg/topic-name
```

### Send with Authentication
```bash
curl -u username:password -d "Authenticated message" https://ntfy.vish.gg/topic-name
```

### Send with Title
```bash
curl -H "Title: Alert Title" -d "Message body" https://ntfy.vish.gg/topic-name
```

## Priority Levels

### Set Message Priority
```bash
# Low priority (1-2)
curl -H "Priority: 1" -d "Debug message" https://ntfy.vish.gg/topic-name

# Normal priority (3) - default
curl -d "Normal message" https://ntfy.vish.gg/topic-name

# High priority (4-5)
curl -H "Priority: 5" -d "CRITICAL ALERT" https://ntfy.vish.gg/topic-name
```

### Priority Reference
- **1 (Min)**: 🔕 Silent, debugging
- **2 (Low)**: 🔔 Quiet notification
- **3 (Default)**: 🔔 Normal notification
- **4 (High)**: 📢 Important, loud
- **5 (Max)**: 🚨 Critical, emergency

## Tags and Emojis

### Common Tags
```bash
# Success notifications
curl -H "Tags: white_check_mark,success" -d "Backup completed" https://ntfy.vish.gg/backups

# Warning notifications
curl -H "Tags: warning,yellow_circle" -d "High CPU usage" https://ntfy.vish.gg/alerts

# Error notifications
curl -H "Tags: x,red_circle" -d "Service failed" https://ntfy.vish.gg/alerts

# Info notifications
curl -H "Tags: information_source,blue_circle" -d "System update" https://ntfy.vish.gg/info
```

### Popular Emoji Tags
- **✅ Success**: `white_check_mark`, `heavy_check_mark`
- **⚠️ Warning**: `warning`, `yellow_circle`
- **❌ Error**: `x`, `red_circle`, `no_entry`
- **🔥 Critical**: `fire`, `rotating_light`
- **📊 Monitoring**: `bar_chart`, `chart_with_upwards_trend`
- **🔧 Maintenance**: `wrench`, `hammer_and_wrench`
- **💾 Backup**: `floppy_disk`, `package`

## Actions and Buttons

### Add Action Buttons
```bash
curl -H "Actions: view, Open Dashboard, https://grafana.local" \
     -d "Check system metrics" \
     https://ntfy.vish.gg/monitoring
```

### Multiple Actions
```bash
curl -H "Actions: view, Dashboard, https://grafana.local; http, Restart, https://portainer.local/restart" \
     -d "Service needs attention" \
     https://ntfy.vish.gg/alerts
```

## Common Homelab Topics

### System Topics
- **`homelab-alerts`** - Critical system alerts
- **`homelab-monitoring`** - Monitoring notifications
- **`homelab-backups`** - Backup status
- **`homelab-updates`** - System updates
- **`homelab-security`** - Security alerts

### Service Topics
- **`plex-alerts`** - Plex Media Server
- **`arr-suite`** - Sonarr/Radarr/Lidarr
- **`gitea-notifications`** - Git events
- **`portainer-alerts`** - Container alerts

## Authentication

### User Credentials
```bash
# Set credentials for session
export NTFY_USER="monitoring"
export NTFY_PASS="REDACTED_PASSWORD"

# Use in curl commands
curl -u "$NTFY_USER:$NTFY_PASS" -d "Message" https://ntfy.vish.gg/topic
```

### Topic Permissions
- **Read (r)**: Subscribe and receive messages
- **Write (w)**: Publish messages to topic
- **Read-Write (rw)**: Full access to topic

## Scheduling and Delays

### Delayed Messages
```bash
# Send in 30 minutes
curl -H "At: $(date -d '+30 minutes' '+%Y-%m-%dT%H:%M:%S')" \
     -d "Scheduled maintenance reminder" \
     https://ntfy.vish.gg/maintenance
```

### Recurring Reminders
```bash
# Daily backup reminder (use with cron)
0 9 * * * curl -d "Daily backup check" https://ntfy.vish.gg/reminders
```

## Monitoring Integration Examples

### Prometheus AlertManager
```bash
# In alertmanager webhook
curl -u alerts:password \
     -H "Title: {{ .GroupLabels.alertname }}" \
     -H "Priority: 4" \
     -H "Tags: fire,prometheus" \
     -d "{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}" \
     https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
```

### Uptime Kuma
```bash
# Service down notification
curl -u monitoring:password \
     -H "Title: Service Down: Plex" \
     -H "Priority: 5" \
     -H "Tags: rotating_light,down" \
     -d "Plex Media Server is not responding" \
     https://ntfy.vish.gg/homelab-monitoring
```

### Backup Scripts
```bash
#!/bin/bash
# backup-notify.sh
if [ "$1" = "success" ]; then
    curl -u backup:password \
         -H "Title: Backup Completed" \
         -H "Tags: white_check_mark,backup" \
         -d "Daily backup completed successfully at $(date)" \
         https://ntfy.vish.gg/homelab-backups
else
    curl -u backup:password \
         -H "Title: Backup Failed" \
         -H "Priority: 4" \
         -H "Tags: x,backup,warning" \
         -d "Daily backup failed: $2" \
         https://ntfy.vish.gg/homelab-backups
fi
```

## Client Subscription

### Command Line
```bash
# Subscribe to topic
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC

# Subscribe with authentication
ntfy subscribe --user monitoring:password https://ntfy.vish.gg/REDACTED_NTFY_TOPIC

# Subscribe to multiple topics
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC,homelab-backups
```

### Mobile Apps
1. **Install NTFY app** (Android/iOS)
2. **Add server**: `https://ntfy.vish.gg`
3. **Subscribe to topics**: Enter topic names
4. **Set credentials**: Username/password if required

## Troubleshooting

### Test Connectivity
```bash
# Basic connectivity test
curl -I https://ntfy.vish.gg

# Test topic publishing
curl -d "Test message" https://ntfy.vish.gg/test

# Test authentication
curl -u username:password -d "Auth test" https://ntfy.vish.gg/test
```

### Debug Message Delivery
```bash
# Check message history
curl -s https://ntfy.vish.gg/topic-name/json

# Monitor real-time messages
curl -N -H "Accept: text/event-stream" https://ntfy.vish.gg/topic-name/sse
```

### Common Error Codes
- **401 Unauthorized**: Invalid credentials
- **403 Forbidden**: No permission for topic
- **404 Not Found**: Topic doesn't exist
- **429 Too Many Requests**: Rate limit exceeded

## Best Practices

### Topic Naming
- Use **kebab-case**: `homelab-alerts`
- Be **descriptive**: `plex-transcoding-alerts`
- Group by **service**: `arr-suite-downloads`
- Include **environment**: `prod-database-alerts`

### Message Content
- **Clear titles**: Describe the issue/event
- **Actionable messages**: Include next steps
- **Consistent formatting**: Use templates
- **Appropriate priority**: Don't overuse high priority

### Security
- **Unique credentials**: Different users for different services
- **Minimal permissions**: Grant only necessary access
- **Regular rotation**: Change passwords periodically
- **Monitor usage**: Track message patterns

---
**Quick Access**: `https://ntfy.vish.gg` | **Admin**: monitoring:password | **Critical**: homelab-alerts