kawaiipunk bdd41929d4 Fix watchdog gaps, image failures and stale reminders
- catch httpx errors on send/heartbeat so a dead signal-api alerts instead
  of failing silently
- never let compose/images block the text post; count failed attempts
- drop reminders for events removed from the feed, using the feed's
  coverage horizon so the 30-event cap does not mark future events gone
- persist feed validators only after a successful parse
- do not seed from an empty feed
- flatten transparent images onto white; catch decompression bombs
- --dump uses a throwaway database
- avoid duplicated postcode in the venue line
- remove dead code; add regression tests
2026-11-18 16:42:47 +00:00

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

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-cli via 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

pip install -e '.[dev]'
pytest

Fixtures are stored as tests/fixtures/*.ics.txt so that *.ics can stay gitignored.

S
Description
An unofficial iCal to Signal messenger bot
Readme GPL-3.0
144 KiB
Languages
Python 99.6%
Dockerfile 0.4%