Birthday Reminder Bot

A small, dependency-free Python bot intended to run once daily on macOS. It hashes chats.json, rebuilds the indexed calendar.json only when needed, then sends reminders for the current local date.

The companion command_bot.py process listens for write-only Telegram commands. It can register the current group or add birthdays, but implements no command to view, edit, or delete stored data. These writes do not run churn.py; the calendar is rebuilt only when the daily reminder process next detects a changed hash.

Setup

1. Create a Telegram bot with BotFather, copy its token, and add the bot to each group that should receive reminders.

2. From this directory, start the command listener:

   TELEGRAM_BOT_TOKEN='your-token' python3 command_bot.py

   On first use, the listener creates a private, empty chats.json; no sample data needs to be copied or removed.

3. In each Telegram group, send /register, followed by one or more /add commands. Stop the local listener with Ctrl-C when setup is complete.

4. Verify the local data and reminder runner:

   python3 churn.py
   python3 birthday_bot.py

The reminder runner sends messages only for birthdays matching the current local date. Birthdays recur every year. Use DD/MM/YYYY, or DD/MM when the birth year is unknown.

If you prefer to configure the data file without Telegram commands, create chats.json with an empty starting structure:

{"chats": []}

Keep chats.json local; it is ignored by Git.

Telegram commands

• /register registers the current group using its Telegram title.
• /add <name> <DD/MM/YYYY|DD/MM> [desc] adds a friend to the current registered group.

Quote names or descriptions containing spaces, for example:

/add "Jane Doe" 21/08/1994 "Likes chocolate cake"

Every successful command returns a summary of the exact addition. Errors explicitly report that no changes were made where relevant. Successful writes are recorded in the local ignored debug.log, including the Telegram username/user ID, friend name, date, description, and destination chat ID.

Both bot processes load TELEGRAM_BOT_TOKEN from .env in this directory (without overriding an already-exported environment variable). chats.json, calendar.json, the fingerprint, .env, and local plist files are ignored by Git. Generated private files are written with owner-only permissions. Never commit a real bot token.

Schedule with launchd (recommended on macOS)

Copy com.local.birthdaybot.plist.template to ~/Library/LaunchAgents/com.local.birthdaybot.plist, replace every REPLACE_WITH_... placeholder, restrict its permissions, then load it:

chmod 600 ~/Library/LaunchAgents/com.local.birthdaybot.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.local.birthdaybot.plist

The template runs daily at 09:00 in the Mac's local timezone. Because launchd has a limited environment, all paths are absolute and the token is supplied explicitly. Note that storing the token in a plist is readable by your user; set the installed plist to mode 600.

For commands, also copy com.local.birthdaybot.commands.plist.template to ~/Library/LaunchAgents/com.local.birthdaybot.commands.plist, replace its placeholders, set it to mode 600, and bootstrap it in the same way. This second job stays alive and uses Telegram long polling, so /register and /add remain available after initial setup.

To reload after editing:

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.local.birthdaybot.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.local.birthdaybot.plist

Privacy behavior

Birthday source, compiled data, command offset, and audit log remain in local ignored files. Reminder API requests contain only the required destination chat_id and rendered message. Command replies contain the requested edit summary, so Telegram necessarily receives the newly submitted name/date/description as part of the original command and summary. The bot never sends existing stored records back to Telegram.

Tests

python3 -m unittest -v