# Notifications

**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)

Telegram notification module for production alerts via @obdpy_bot. Integrates with the hooks system (`opendeviationbar.hooks`) to send formatted HTML messages on cache writes, validation events, gap detection, and heartbeat status.

---

## Files

| File          | LOC  | Purpose                                                                                      |
| ------------- | ---- | -------------------------------------------------------------------------------------------- |
| `__init__.py` | ~15  | Package docstring with usage examples; no re-exports (`__all__ = []`)                        |
| `telegram.py` | ~390 | `send_telegram()`, `delete_telegram_message()`, hook callbacks, config loader, context block |

## Configuration

| Env Var                             | Required | Default    | Description                 |
| ----------------------------------- | -------- | ---------- | --------------------------- |
| `OPENDEVIATIONBAR_TELEGRAM_TOKEN`   | Yes      | --         | Bot token from @BotFather   |
| `OPENDEVIATIONBAR_TELEGRAM_CHAT_ID` | No       | `90417581` | Telegram chat ID for alerts |

**Where secrets live**: `deploy/opendeviationbar.local.env` on bigblack (non-git-tracked), or `.mise.local.toml` for local dev.

## Key Functions

| Function                          | Purpose                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| `send_telegram(message)`          | Send HTML message via bot API; returns message ID or `False`                        |
| `delete_telegram_message(msg_id)` | Delete a previously sent message (ephemeral heartbeat pattern)                      |
| `enable_telegram_notifications()` | Register `telegram_notify` callback for ALL hook events                             |
| `enable_failure_notifications()`  | Register callback for `*_FAILED` events only                                        |
| `telegram_notify(payload)`        | Hook callback: formats `HookPayload` to HTML with context block                     |
| `set_start_time(t)`               | Override module start time for uptime tracking (called at sidecar/kintsugi startup) |
| `_build_context_block(service)`   | Appends host, version, uptime, ouroboros mode, tier toggles to every message        |

## Usage Patterns

Callers import directly from `telegram.py`, not via `__init__.py`:

```python
# Hook integration (sidecar, kintsugi)
from opendeviationbar.notify.telegram import enable_telegram_notifications
enable_telegram_notifications()

# Direct messaging (heartbeat, scripts)
from opendeviationbar.notify.telegram import send_telegram, delete_telegram_message
msg_id = send_telegram("<b>Alert:</b> Stathera gap detected")
delete_telegram_message(msg_id)  # ephemeral pattern
```

**Consumers**: `sidecar.py`, `kintsugi.py`, `scripts/health_heartbeat.py`, `scripts/tick_cache_seeder.py`

## Related

- [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) -- Parent spoke (Python API layer)
- [/CLAUDE.md](/CLAUDE.md) -- Project hub
- [/deploy/CLAUDE.md](/deploy/CLAUDE.md) -- Env files SSoT (where tokens are stored on bigblack)
- [/scripts/CLAUDE.md](/scripts/CLAUDE.md) -- Scripts that use Telegram notifications
