# SyncTide v1.6.0 — Update Log

**Release date:** 2026-04-17
**Schema version:** 11 (migrations 010 + 011 required)
**Previous version:** v1.5.0

---

## What's new

### Multi-channel messaging
- **Twilio WhatsApp**: Send alarm notifications via WhatsApp through the Twilio API
- **Telegram Bot**: Send messages via Telegram Bot API to individual chats or groups
- **Email (SMTP)**: Send alarm notifications via any SMTP server (Gmail, Outlook, on-prem)
- Channel type is now **optional** on alarm rules — if not set, the system uses whatever default gateway is available

### Ack-driven escalation (optional per rule)
- **Require message acknowledgment** — optional checkbox on each alarm rule
- When **enabled** (`require_ack=True`):
  - Each message includes a unique **ack token** (e.g. "Reply ACK-abc123 to acknowledge")
  - If the recipient doesn't reply within `ack_timeout_seconds` (default 300s), the system auto-escalates to the next person
  - Acknowledgment via SMS/WhatsApp/Telegram reply, email reply, or API: `POST /messaging/acknowledge/{token}`
  - When someone acknowledges, all pending messages for the same alarm are cancelled
- When **disabled** (`require_ack=False`, the default):
  - No ack token is appended to messages
  - Escalation uses the `delay_seconds` configured on escalation list members
  - Escalation only stops when the alarm is acknowledged in the platform UI

### Map style fix
- Home page map now uses **free CARTO tiles** (light and dark modes) — works out of the box without any API key
- Optional **Mapbox satellite** style available by setting `SYNCTIDE_MAPBOX_API_KEY` in `.env`

### UI improvements
- Messaging Center page: new gateway configuration forms for Twilio, Telegram, SMTP
- Alarm rules: channel type selector with "Any (default gateway)" option
- Alarm rules: ack timeout configuration field with help text
- History view: shows channel type badge, recipient address, ack status per message

---

## Migrations required

Run migrations `010_multi_channel_ack.sql` and `011_optional_ack.sql` before starting the updated backend.

**Migration 010 changes:**
- Widens CHECK constraints on `messaging_gateways`, `messaging_alarm_rules`, `messaging_history` to allow `telegram`, `smtp`, `email` values
- Adds `recipient_address TEXT` to `messaging_history`
- Adds `ack_token TEXT` to `messaging_history` (with unique index)
- Adds `ack_timeout_seconds INTEGER DEFAULT 300` to `messaging_alarm_rules`
- Makes `messaging_alarm_rules.channel_type` nullable (NULL = any channel)
- Makes `messaging_history.recipient_phone` nullable (email/telegram don't have phone numbers)

**Migration 011 changes:**
- Adds `require_ack BOOLEAN DEFAULT FALSE` to `messaging_alarm_rules`

**Both migrations are backwards compatible** — all existing data and SMS workflows continue to work unchanged. Existing rules default to `require_ack=FALSE` (delay-based escalation, same behavior as before).

---

## Files changed

| File | Change | Recompile |
|------|--------|-----------|
| `migrations/010_multi_channel_ack.sql` | New migration | No |
| `messaging_engine.py` | 3 new channel classes (Twilio, Telegram, SMTP) | Yes |
| `main.py` | Ack-driven escalation, multi-channel routing, ack endpoint | Yes |
| `app_core.py` | Map style fix (CARTO tiles) | Yes |
| `settings.py` | `MAPBOX_API_KEY` setting | Yes |
| `i18n.py` | 50+ new translation keys | Yes |
| `version.py` | Bumped to 1.6.0 | Yes |
| `pages/3_SMS_Center.py` | Multi-channel gateway/rule UI | No (hot-reload) |

---

## Deployment steps

1. Stop backend service
2. Run migration 010 against the database
3. Copy updated `.pyd` files: `messaging_engine`, `main`, `app_core`, `settings`, `i18n`, `version`
4. Copy `pages/3_SMS_Center.py` (plain Python, no compile needed)
5. Copy `migrations/010_multi_channel_ack.sql`
6. Update `integrity_manifest.json` with new SHA-256 hashes
7. Start backend service
8. Verify at `/version` — should show `1.6.0`

---

## Optional configuration

### Mapbox satellite tiles
Add to `.env`:
```
SYNCTIDE_MAPBOX_API_KEY=pk.eyJ1I...your_key_here
```

### Telegram Bot
1. Create a bot via @BotFather on Telegram
2. Add a gateway in Messaging Center > Configuration > Add Gateway
3. Select type "Telegram Bot", enter the bot token
4. Set channel type to "telegram"

### SMTP Email
1. Add a gateway with type "Email (SMTP)"
2. Configure host, port, TLS, credentials, from address
3. For Gmail: use an App Password (not your regular password)

### Twilio WhatsApp
1. Create a Twilio account and enable the WhatsApp sandbox
2. Add a gateway with type "Twilio (WhatsApp)"
3. Enter Account SID, Auth Token, and From Number