88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
# ntfy → Matrix bridge
|
|
|
|
A small daemon that watches a set of [ntfy](https://ntfy.sh) topics and forwards
|
|
every notification to a Matrix room. Define which topics go where in a simple
|
|
YAML config.
|
|
|
|
It is built to run unattended:
|
|
|
|
- one streaming connection per mapping, with exponential-backoff reconnect
|
|
- resume via ntfy's `since=<message_id>`, so nothing is lost across reconnects
|
|
or restarts (the last-forwarded id is persisted to `state.json`)
|
|
- a single Matrix sender that retries on failure; the resume cursor only
|
|
advances once the homeserver has accepted the message (at-least-once delivery)
|
|
|
|
> **Unencrypted rooms only.** The target Matrix room must not be end-to-end
|
|
> encrypted. Supporting E2EE would require a persistent crypto store, a stable
|
|
> device id, and a sync loop — deliberately out of scope here.
|
|
|
|
## Setup
|
|
|
|
### 1. Create a bot account and get an access token
|
|
|
|
Create a normal user on your homeserver for the bot (e.g. `@ntfybot:example.org`),
|
|
then run the helper to log in and print an access token:
|
|
|
|
```bash
|
|
python login.py
|
|
```
|
|
|
|
Copy the printed `access_token` (and optionally `device_id`) for the next step.
|
|
|
|
### 2. Configure
|
|
|
|
```bash
|
|
cp config.example.yaml config.yaml
|
|
```
|
|
|
|
Edit `config.yaml`. The token is best supplied via the environment rather than
|
|
written into the file — `${VAR}` in any value is expanded from the environment:
|
|
|
|
```bash
|
|
export MATRIX_ACCESS_TOKEN="syt_...."
|
|
```
|
|
|
|
Each entry under `mappings` ties a set of topics on one ntfy server to one
|
|
Matrix room. Use the room's **internal id** (`!abcd...:example.org`, found under
|
|
room settings → Advanced), not its human alias. Make sure the bot has **joined**
|
|
each target room.
|
|
|
|
### 3. Run
|
|
|
|
```bash
|
|
python bridge.py --config config.yaml
|
|
```
|
|
|
|
You should see a `subscribed` line per mapping. Publish a test message:
|
|
|
|
```bash
|
|
curl -d "hello from ntfy" https://ntfy.sh/your-topic
|
|
```
|
|
|
|
## Running as a service (systemd)
|
|
|
|
```bash
|
|
sudo useradd --system --home /opt/ntfy-matrix-bridge ntfybridge
|
|
sudo cp -r . /opt/ntfy-matrix-bridge
|
|
sudo python3 -m venv /opt/ntfy-matrix-bridge/venv
|
|
sudo /opt/ntfy-matrix-bridge/venv/bin/pip install -r /opt/ntfy-matrix-bridge/requirements.txt
|
|
sudo cp ntfy-matrix-bridge.service /etc/systemd/system/
|
|
# edit the unit to set MATRIX_ACCESS_TOKEN (or point EnvironmentFile at a secrets file)
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now ntfy-matrix-bridge
|
|
journalctl -u ntfy-matrix-bridge -f
|
|
```
|
|
|
|
## Notes
|
|
|
|
- **Formatting.** Title is bold, the body follows, recognised ntfy tags become
|
|
emoji (others are listed as text), and `click`/attachment URLs become links.
|
|
Priority 4/5 get a coloured marker.
|
|
- **`msgtype`.** `m.text` (default) triggers notifications in clients; switch a
|
|
mapping to `m.notice` if you want it quieter.
|
|
- **`priority_min`.** Optionally drop low-priority messages per mapping.
|
|
- **State.** Delete `state.json` to forget the resume position; on the next
|
|
start each mapping begins live (no historical replay).
|
|
- ntfy.sh caches messages for a few hours, so short outages are recoverable; a
|
|
self-hosted server needs caching enabled for resume to work across restarts.
|