# calbot — iCalendar → Signal Watches an iCalendar feed (built for The Events Calendar / MCR Commons) and posts events to a Signal group, with the event's poster image attached. Posts look like this: ``` Folk Night #November #November14 4.30-6.30pm Old Print Works B12 9AH https://commonscalendar.uk/event/folk-night/ ``` ## How it behaves - **Announcements** — a newly seen event is posted within one refresh interval, deferred to the next posting window (`08:00–10:00` or `18:00–21:00` by default). - **Reminders** — every event is posted again 3 days before it starts. If the event was added less than 3 days ahead, the reminder goes out on the morning of the event instead. An imminent event breaks the posting window rather than arriving late. - **Images** — taken from the feed's `ATTACH` property (The Events Calendar emits the featured image), falling back to the event page's JSON-LD / `og:image`. Every post carries an image. - **Recurring events** — the feed pre-expands occurrences, but announcements are deduplicated per series, so adding a weekly event produces one announcement. - **First run** — seeds silently (`announce.backfill = false`); reminders still work for everything already in the feed. - **Watchdog** — messages you on Signal if the feed stops working, parses to nothing, or sending keeps failing. ## Setup ### 1. Link a Signal account Linking as a secondary device is the quickest route: the bot posts **as your own number**. For a separate bot identity you must register a dedicated number instead (see `signal-cli-rest-api` docs). ```bash mkdir -p signal-data data cache docker compose up -d signal-api ``` Open and scan the QR code from **Signal → Settings → Linked devices**. ```bash # the linked number: curl -s http://localhost:8080/v1/accounts # groups for that number — copy the internal_id (starts with "group."): curl -s http://localhost:8080/v1/groups/+447700900000 | jq ``` ### 2. Configure ```bash cp config.example.toml config.toml chmod 600 config.toml $EDITOR config.toml ``` Fill in `signal.number`, `signal.group_id`, and `calendar.url`. `webcal://` URLs are accepted and fetched over https. ### 3. Check, preview, run ```bash # is the account linked and the config valid? docker compose run --rm bot python -m calbot --check # print the rendered posts for the feed without sending anything docker compose run --rm bot python -m calbot --dump # start the bot docker compose up -d bot docker compose logs -f bot ``` `--once` runs a single tick and exits. ## Install by hand ```bash python -m venv .venv && . .venv/bin/activate pip install -e '.[dev]' calbot --config config.toml --dump calbot --config config.toml ``` ## Files that matter | Path | Purpose | |---|---| | `config.toml` | numbers, group, feed, behaviour (never committed) | | `signal-data/` | linked-device keys — **back this up**, losing it means re-linking | | `data/calbot.sqlite3` | event/outbox/delivery state (safe to delete to re-seed) | | `cache/images/` | downscaled posters | Deleting `data/calbot.sqlite3` resets dedupe state: on the next run everything is seeded silently again, so you will not get a flood, but new-series detection restarts from that moment. ## Notes and limits - Signal has no bot API; this uses [`signal-cli`](https://github.com/AsamK/signal-cli) via [`signal-cli-rest-api`](https://github.com/bbernhard/signal-cli-rest-api). - Delivery is **at-least-once**. A crash between sending and recording can duplicate one post. - The feed is capped by The Events Calendar (30 events by default) and may omit past events; the bot only knows what the feed contains. - Venue/postcode come from the ICS `LOCATION` when present (this feed often has none), then from the event page's structured data, then from the description. ## Tests ```bash pip install -e '.[dev]' pytest ``` Fixtures are stored as `tests/fixtures/*.ics.txt` so that `*.ics` can stay gitignored.