ghebby/telegram_bot_bridge repository overview

telegram_bot_bridge is a production-oriented Telegram bot that turns chat into actions: it routes natural language through an LLM (OpenAI by default), runs pluggable modules with pure business logic, and keeps Telegram-specific UI in one place.

⁠What it does

• AI intent routing — Detects what the user wants; falls back to conversational chat when no intent matches.
• Contacts — Per-user isolated address book (add / list / delete).
• Email — Sends mail through an n8n webhook; draft preview and confirmation before send.
• Reminders & jobs — One-off and recurring reminders; scheduled actions (e.g. email at a time) with validated schedules and immutable approved payloads after confirmation.
• Job management — List and delete scheduled jobs by id or index.
• Access control — JSON allowlist with admin and user roles (/whitelist for admins).
• Ops-friendly — Session logging, optional pre-match for common commands (fewer tokens), cached system prompt / capabilities (build step), JSON persistence for allowlist, contacts, and jobs.

⁠Commands

Italian is used for bot-facing responses and the AI-generated capabilities summary (configurable via your build).

⁠Running with Docker

Mount persistent data and supply env vars (see repository README / QUICKSTART for BOT_TOKEN, OPENAI_TOKEN, optional n8n mail webhook, and allowed_telegram_ids.json). Run build_capabilities.py when you change modules so capabilities_cache.json stays in sync.

⁠Extending

Add a folder under modules/ with skill.md + INTENTS in __init__.py, register it in ACTIVE_MODULES, rebuild capabilities. Swap LLMs by implementing the AIProvider interface.

---

Stack: Python · python-telegram-bot · OpenAI (default) · optional n8n for outbound mail · JSON file storage.