# Quick Matrix Alerting Setup

## Step 1: Get Matrix Account
1. Go to https://app.element.io or install Element app
2. Create account or login with existing Matrix account

## Step 2: Get Access Token

### Method 1: Element Web (Recommended)
1. Open Element in browser: https://app.element.io
2. Login to your account
3. Click Settings (gear icon) → Help & About → Advanced
4. Copy your "Access Token" (starts with `syt_...` or similar)

### Method 2: Command Line
```bash
curl -X POST https://matrix.org/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "your_username",
    "password": "your_password"
  }'
```

## Step 3: Create Alert Room
1. In Element, click "+" to create new room
2. Name: "Water Level Alerts"
3. Set to Private
4. Copy the room ID from room settings (format: `!roomid:matrix.org`)

## Step 4: Configure .env File
Add these to your `.env` file:
```bash
# Matrix Alerting Configuration
MATRIX_HOMESERVER=https://matrix.org
MATRIX_ACCESS_TOKEN=syt_your_access_token_here
MATRIX_ROOM_ID=!your_room_id:matrix.org

# Grafana Integration (optional)
GRAFANA_URL=http://localhost:3000
```

## Step 5: Restart and check
The Matrix messages are sent by `ping-collector` (the Rust service, with
`FORECAST_IN_COLLECTOR=true`), together with the ntfy notifications:

```bash
sudo systemctl restart ping-collector
journalctl -u ping-collector | grep -i matrix      # "Matrix notifications: room ... on ..."
# what would be sent right now (ntfy and Matrix), changing nothing:
sudo -u water-monitor /opt/thailand-water-monitor/bin/ping-collector notify --dry-run
```

## What the room receives
The same transitions as the ntfy topics (docs/NOTIFICATIONS.md), each once:
a station crossing its warning or danger level and back (0.10 m hysteresis),
the P.1 early-warning outlook turning on and off, and the gauge feed going
stale or recovering. ntfy's per-topic summaries ("Ping River: warning level
reached") are not repeated in the room. For example:

```
⚠️ **Warning level at P.1**
Nawarat Bridge, Chiang Mai city: 3.75 m at 18 Oct 14:00, above the warning level of 3.70 m.

📈 Dashboard: https://water.buildfor.life/
```

The room has its own delivery state (`matrix:` keys in `notification_state`),
so a Matrix outage is retried on Matrix only and does not re-send ntfy.

The old `run.py --alert-check` cron job (every 15 minutes, repeating an alert
for as long as a level stayed high) is replaced by this;
`scripts/install_collector.sh` comments it out of the crontab once
ping-collector sends Matrix, keeping a backup next to the app.

## Troubleshooting
- **HTTP 401/403** in `journalctl -u ping-collector`: the access token is invalid
  or the account is not in the room.
- **Room not found**: the room ID needs the `!` prefix and the `:homeserver`
  suffix.
- **Nothing sent**: there was no transition; `ping-collector notify --dry-run`
  shows the readings judged and what would be sent.