tidaldb/.sdlc/tools/telegram-recap

telegram-recap

Fetches Telegram chat messages from the configured time window and emails a digest via SMTP. Delegates all logic to sdlc telegram digest — no duplicate implementation.

Prerequisites

1. A Telegram bot created via @BotFather
2. The bot added to the chats you want to digest
3. sdlc telegram poll running (or having run) to populate the local message database
4. SMTP credentials (e.g. Resend, SendGrid, Gmail SMTP)

Setup

1. Configure secrets

The tool requires these environment variables. Set them in your orchestrator secrets or shell:

Variable	Description
TELEGRAM_BOT_TOKEN	Bot API token from @BotFather
SMTP_HOST	SMTP server hostname (e.g. smtp.resend.com)
SMTP_PORT	SMTP port (587 for STARTTLS, 465 for SSL)
SMTP_USERNAME	SMTP auth username
SMTP_PASSWORD	SMTP auth password or API key
SMTP_FROM	From address (e.g. digest@yourdomain.com)
SMTP_TO	Recipient(s), comma-separated

2. Run setup to verify

sdlc tool run telegram-recap --setup

This calls sdlc telegram status to verify the bot token and database connectivity. Returns { ok: true, data: { status_output: "..." } } on success.

Usage

Dry run (preview without sending)

sdlc tool run telegram-recap --input '{"dry_run": true}'

Send digest

sdlc tool run telegram-recap --input '{}'

Custom window

# Last 48 hours instead of the default 24
sdlc tool run telegram-recap --input '{"window_hours": 48}'

Specific chat IDs

sdlc tool run telegram-recap --input '{"chat_ids": ["-100123456789"]}'

Output

{
  "ok": true,
  "data": {
    "dry_run": false,
    "total_messages": 42,
    "chat_count": 3,
    "period_start": "2026-03-01T08:00:00Z",
    "period_end": "2026-03-02T08:00:00Z",
    "sent_to": ["you@example.com"]
  },
  "duration_ms": 1234
}

Scheduling with the orchestrator

Use the sdlc orchestrator for recurrence instead of systemd:

# Daily digest at the current time
sdlc orchestrate add telegram-recap \
  --tool telegram-recap \
  --input '{}' \
  --at "now" \
  --every 86400

This removes the need for systemd timers. The orchestrator runs the tool on schedule and streams results to the sdlc UI via SSE.

Troubleshooting

"Bot token check failed" → TELEGRAM_BOT_TOKEN is missing or invalid. Verify with sdlc telegram status.

"sdlc telegram digest failed" → Check that sdlc telegram poll has been running and the database exists at .sdlc/telegram/messages.db. Run sdlc telegram status for diagnostics.

SMTP errors → Check SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD. Common mistake: using port 465 with STARTTLS or port 587 with SSL — match port to protocol.

No messages in digest → The configured chat IDs may not match what the bot has access to, or the time window contains no messages. Try --input '{"window_hours": 168}' (7 days) to widen the window.