- feed fetch with ETag/Last-Modified caching - iCalendar parsing/expansion with TEC series detection - posting-window scheduler with 3-day reminders and day-of fallback - image attachments from ATTACH, downscaled via Pillow - SQLite outbox with idempotent deliveries - watchdog alerts to Note to Self - Docker Compose with signal-cli-rest-api
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:00or18:00–21:00by 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
ATTACHproperty (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).
mkdir -p signal-data data cache
docker compose up -d signal-api
Open http://localhost:8080/v1/qrcodelink?device_name=calbot and scan the QR code from Signal → Settings → Linked devices.
# 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
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
# 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
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-cliviasignal-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
LOCATIONwhen present (this feed often has none), then from the event page's structured data, then from the description.
Tests
pip install -e '.[dev]'
pytest
Fixtures are stored as tests/fixtures/*.ics.txt so that *.ics can stay
gitignored.