111 lines
3.3 KiB
Markdown
111 lines
3.3 KiB
Markdown
# ntfy.sh Push Notifications Setup
|
|
|
|
CheddahBot sends push notifications to your phone and desktop via [ntfy.sh](https://ntfy.sh) when tasks complete, reports are ready, or errors occur.
|
|
|
|
## 1. Install the ntfy App
|
|
|
|
- **Android:** [Play Store](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
|
|
- **iOS:** [App Store](https://apps.apple.com/us/app/ntfy/id1625396347)
|
|
- **Desktop:** Open [ntfy.sh](https://ntfy.sh) in your browser and enable browser notifications when prompted
|
|
|
|
## 2. Pick Topic Names
|
|
|
|
Topics are like channels. Anyone who knows the topic name can subscribe, so use random strings:
|
|
|
|
```
|
|
cheddahbot-a8f3k9x2m7
|
|
cheddahbot-errors-p4w2j6n8
|
|
```
|
|
|
|
Generate your own — any random string works. No account or registration needed.
|
|
|
|
## 3. Subscribe to Your Topics
|
|
|
|
**Phone app:**
|
|
1. Open the ntfy app
|
|
2. Tap the + button
|
|
3. Enter your topic name (e.g. `cheddahbot-a8f3k9x2m7`)
|
|
4. Server: `https://ntfy.sh` (default)
|
|
5. Repeat for your errors topic
|
|
|
|
**Browser:**
|
|
1. Go to [ntfy.sh](https://ntfy.sh)
|
|
2. Click "Subscribe to topic"
|
|
3. Enter the same topic names
|
|
4. Allow browser notifications when prompted
|
|
|
|
## 4. Add Topics to .env
|
|
|
|
Add these lines to your `.env` file in the CheddahBot root:
|
|
|
|
```
|
|
NTFY_TOPIC_HUMAN_ACTION=cheddahbot-a8f3k9x2m7
|
|
NTFY_TOPIC_ERRORS=cheddahbot-errors-p4w2j6n8
|
|
```
|
|
|
|
Replace with your actual topic names.
|
|
|
|
## 5. Restart CheddahBot
|
|
|
|
Kill the running instance and restart:
|
|
|
|
```bash
|
|
uv run python -m cheddahbot
|
|
```
|
|
|
|
You should see in the startup logs:
|
|
|
|
```
|
|
ntfy notifier initialized with 2 channel(s): human_action, errors
|
|
ntfy notifier subscribed to notification bus
|
|
```
|
|
|
|
## What Gets Notified
|
|
|
|
### human_action channel (high priority)
|
|
Notifications where you need to do something:
|
|
- Cora report finished and ready
|
|
- Press release completed
|
|
- Content outline ready for review
|
|
- Content optimization completed
|
|
- Link building pipeline finished
|
|
- Cora report distributed to inbox
|
|
|
|
### errors channel (urgent priority)
|
|
Notifications when something went wrong:
|
|
- ClickUp task failed or was skipped
|
|
- AutoCora job failed
|
|
- Link building pipeline error
|
|
- Content pipeline error
|
|
- Missing ClickUp field matches
|
|
- File copy failures
|
|
|
|
## Configuration
|
|
|
|
Channel routing is configured in `config.yaml` under the `ntfy:` section. Each channel has:
|
|
|
|
- `topic_env_var` — which env var holds the topic name
|
|
- `categories` — notification categories to listen to (`clickup`, `autocora`, `linkbuilding`, `content`)
|
|
- `include_patterns` — regex patterns the message must match (at least one)
|
|
- `exclude_patterns` — regex patterns that reject the message (takes priority over include)
|
|
- `priority` — ntfy priority level: `min`, `low`, `default`, `high`, `urgent`
|
|
- `tags` — emoji shortcodes shown on the notification (e.g. `white_check_mark`, `rotating_light`)
|
|
|
|
### Adding a New Channel
|
|
|
|
1. Add a new entry under `ntfy.channels` in `config.yaml`
|
|
2. Add the topic env var to `.env`
|
|
3. Subscribe to the topic in your ntfy app
|
|
4. Restart CheddahBot
|
|
|
|
### Privacy
|
|
|
|
The public ntfy.sh server has no authentication by default. Your topic name is the only security — use a long random string to make it unguessable. Alternatively:
|
|
|
|
- Create a free ntfy.sh account and set read/write ACLs on your topics
|
|
- Self-host ntfy (single binary) and set `server: http://localhost:8080` in config.yaml
|
|
|
|
### Disabling
|
|
|
|
Set `enabled: false` in the `ntfy:` section of `config.yaml`, or remove the env vars from `.env`.
|