Recordabot

Recordabot is a multi-channel reminder service built with FastAPI. It schedules recurring or cron-based reminders and delivers them through Telegram, WhatsApp, or email, with optional dynamic content generation from an external provider.

Why it matters

• Product-oriented backend project with a clear API surface.
• Combines scheduling, messaging integrations, and operational controls.
• Useful as a reference for bots, notification systems, and automation workflows.

Highlights

• Interval and cron scheduling.
• Telegram, WhatsApp (Twilio), and SMTP email delivery.
• Flexible Telegram payloads for rich messages.
• Optional external message provider for dynamic content generation.
• REST API plus CLI utilities.
• SQLite persistence and Docker-based local deployment.

Stack

• Python
• FastAPI
• APScheduler
• SQLModel
• python-telegram-bot
• Docker

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

The API is available at http://localhost:8000.

Docker

docker compose up --build

Configuration

Copy .env.example to .env and set the relevant values.

Core variables:

• TELEGRAM_BOT_TOKEN
• DATABASE_URL
• SCHEDULER_TIMEZONE
• MESSAGE_PROVIDER_URL
• MESSAGE_PROVIDER_TIMEOUT_SECONDS
• MESSAGE_PROVIDER_AUTH_HEADER
• EMAIL_SMTP_HOST, EMAIL_SMTP_PORT, EMAIL_SMTP_USER, EMAIL_SMTP_PASSWORD, EMAIL_FROM, EMAIL_USE_TLS
• WHATSAPP_TWILIO_ACCOUNT_SID, WHATSAPP_TWILIO_AUTH_TOKEN, WHATSAPP_FROM_NUMBER

API surface

Main endpoints:

• POST /reminders
• GET /reminders
• PATCH /reminders/{id}
• DELETE /reminders/{id}
• POST /reminders/{id}/send-now
• POST /reminders/{id}/controls
• POST /telegram/webhook

Example reminder payload:

{
  "recipient": "123456789",
  "channel": "telegram",
  "schedule_type": "interval",
  "schedule_value": "3600",
  "payload": {
    "method": "sendMessage",
    "params": {
      "text": "Hello from Recordabot"
    }
  }
}

CLI examples

python -m app.cli send-telegram --recipient 123456789 --method sendMessage --params-json '{"text":"hello"}'
python -m app.cli send-email --to user@example.com --subject "Hello" --body "Message"
python -m app.cli send-whatsapp --to +34123456789 --body "Hello"
python -m app.cli set-webhook --url https://your-domain.com/telegram/webhook

Dynamic content provider

When MESSAGE_PROVIDER_URL is configured, Recordabot can fetch a replacement payload before sending a reminder. If the provider fails, the original payload is used as a fallback.

Notes

• Reminder state is persisted in SQLite and restored at startup.
• Telegram controls support pause, resume, send now, skip next, and refresh payload actions.

License

MIT