{"id":50673007,"url":"https://github.com/yniyniyni/telegram-summarizer-bot","last_synced_at":"2026-06-08T13:02:47.833Z","repository":{"id":359402193,"uuid":"1245895280","full_name":"yniyniyni/telegram-summarizer-bot","owner":"yniyniyni","description":"An asynchronous Telegram bot built with Node.js for automatic message logging and summarization in group chats using the Google Gemini.","archived":false,"fork":false,"pushed_at":"2026-05-22T00:52:08.000Z","size":220,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T02:48:56.261Z","etag":null,"topics":["gemini","gemini-api","summarization","telegram","telegrambot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yniyniyni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T17:01:08.000Z","updated_at":"2026-05-22T01:14:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yniyniyni/telegram-summarizer-bot","commit_stats":null,"previous_names":["yniyniyni/telegram-gemini-summarizer-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yniyniyni/telegram-summarizer-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yniyniyni%2Ftelegram-summarizer-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yniyniyni%2Ftelegram-summarizer-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yniyniyni%2Ftelegram-summarizer-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yniyniyni%2Ftelegram-summarizer-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yniyniyni","download_url":"https://codeload.github.com/yniyniyni/telegram-summarizer-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yniyniyni%2Ftelegram-summarizer-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34063159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gemini","gemini-api","summarization","telegram","telegrambot"],"created_at":"2026-06-08T13:02:47.068Z","updated_at":"2026-06-08T13:02:47.825Z","avatar_url":"https://github.com/yniyniyni.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Chat Summarizer Bot (TypeScript)\n\n[На русском](docs/README_ru.md)\n\nAn asynchronous Telegram bot built with Node.js, TypeScript, the `telegraf` framework, and the official `@google/genai` SDK for automatic message logging and summarization in group chats using the **Gemini 3.1 Flash Lite** model.\n\n**WARNING!!! 100% AI slop project** written by Gemini 3.5 Flash from scratch. Use with caution.\n\n## Features\n*   **Multi-language Support**: Configurable bot interface and summary language (English and Russian are fully supported; see `.env` settings). Supports natural time parsing in both languages.\n*   **Real-time logging**: The bot tracks and logs text messages and media captions into a local SQLite database.\n*   **Edit synchronization**: Automatically updates message content in the database if a user edits their message in Telegram.\n*   **Memory safe**: A background cron job cleans up messages older than 30 days once a day.\n*   **Secure database permissions**: Creates the SQLite database directory with mode `0700` when missing and sets the database file itself to mode `0600` on Linux/macOS.\n*   **Markup protection**: Sanitizes Gemini output for Telegram HTML, converts basic Markdown formatting, and falls back to plain text if Telegram still rejects the markup.\n*   **Topic (Thread) compatibility**: Correctly handles and stores `thread_id` for forum-like supergroups.\n*   **Private chat support**: In private chats, trigger keywords start summarization; other messages receive a short welcome/help response.\n\n---\n\n## 🛠️ Bot Preparation and Configuration\n\n### 1. Creating a Telegram Bot\n1. Chat with [@BotFather](https://t.me/BotFather) on Telegram.\n2. Create a new bot using the `/newbot` command and copy the provided **Telegram Bot Token**.\n\n### 2. Disabling Privacy Mode (Important!)\nBy default, Telegram bots cannot read group messages unless they are directly mentioned. To allow the bot to collect history for summarization:\n1. In the chat with [@BotFather](https://t.me/BotFather), send the `/mybots` command and select your bot.\n2. Go to **Bot Settings** -\u003e **Group Privacy**.\n3. Click **Turn off** (you should see a message saying `Privacy mode is disabled`).\n4. If the bot is already in your group, **remove it and add it back** for the settings to apply.\n5. *(Recommended)*: Make the bot an administrator in the group and grant it permission to read messages.\n\n### 3. Getting Gemini API Key\nObtain a free or paid API key from [Google AI Studio](https://aistudio.google.com/).\n\n### 4. Advanced Configuration (Optional)\nYou can configure rate limits, privacy modes, and whitelist specific chat IDs in your `.env` file to protect your Gemini API quota:\n*   **Rate Limiting**:\n    *   `RATE_LIMIT_MAX_REQUESTS`: Set the maximum number of summarization requests allowed per chat in the window. Disabled if unset or set to `0`; invalid or negative values fail closed and block requests temporarily.\n    *   `RATE_LIMIT_WINDOW_SEC`: The duration of the window in seconds (defaults to `3600` - 1 hour; invalid values fall back to `3600`).\n*   **Chat ID Authorization**:\n    *   `ALLOWED_CHATS`: A comma-separated list of numeric chat IDs allowed to use the bot (e.g., `-100123456789,-100987654321,12345678`).\n    *   `ALLOWED_USERS`: A comma-separated list of numeric Telegram user IDs allowed to interact with the bot in private messages (DMs). If configured, it restricts private chats even if `ALLOW_ALL_CHATS` is set to `true`.\n    *   `ALLOW_ALL_CHATS`: Set to `true` to explicitly disable authorization checks and allow all chats. By default, authorization operates in a **fail-closed** mode: if `ALLOW_ALL_CHATS` is not `true` and both `ALLOWED_CHATS` and `ALLOWED_USERS` are empty or unset, all chats will be unauthorized by default.\n*   **PII Minimization**:\n    *   `REDACT_USER_IDENTITIES`: Set to `true` to enable user identity redaction in transcripts. In this mode, real names and usernames in message headers and bodies are replaced with stable pseudonyms (e.g., `User 1`, `User 2`), and any other username mentions are replaced with `@user_redacted`.\n*   **Logging**:\n    *   `DEBUG=true`, `DEBUG=1`, or `LOG_LEVEL=debug`: Enables debug logs. Non-debug logs are always printed.\n*   **Database path**:\n    *   `DB_PATH`: Defaults to `data/bot_messages.db`. Values containing `..` are rejected on startup.\n*   **Gemini API key**:\n    *   `GEMINI_API_KEY`: Primary API key variable. `GOOGLE_API_KEY` is also accepted as a fallback.\n\n---\n\n## 🚀 Installation and Run\n\nFor a detailed deployment guide on Linux servers (Debian/Ubuntu and Alma/Rocky Linux), please refer to the [Deployment Guide](docs/deployment.md).\n\n### Prerequisites\n*   Node.js v20.17.0 or higher (tested on Node.js v22)\n\n### Installation Steps\n\n1.  Clone the repository and navigate to its folder.\n2.  Install the required dependencies using npm:\n    ```bash\n    npm install\n    ```\n3.  Create a `.env` configuration file based on the example:\n    ```bash\n    cp .env.example .env\n    ```\n4.  Fill in `.env` with your tokens:\n    ```env\n    TELEGRAM_BOT_TOKEN=your_telegram_bot_token\n    GEMINI_API_KEY=your_gemini_api_key\n    DB_PATH=data/bot_messages.db\n    DEFAULT_TIMEZONE=Europe/Moscow\n    BOT_LANGUAGE=en\n    ALLOW_ALL_CHATS=true\n    REDACT_USER_IDENTITIES=false\n    ```\n\n### Testing Functionality\nYou can run the full built-in test suite before starting the bot:\n```bash\nnpm test\n```\nIt runs database, main handler, timeframe parser, utility, and summarizer tests. You can also run individual suites:\n```bash\nnpm run test:db\nnpm run test:main\nnpm run test:parser\nnpm run test:utils\nnpm run test:summarizer\n```\n\n### Building the Project (TypeScript compilation)\nTo compile the TypeScript project into JavaScript, run:\n```bash\nnpm run build\n```\nCompiled files will be saved in the `dist/` directory.\n\n### Running the Bot\nStart the bot directly using `tsx` (TypeScript execute):\n```bash\nnpm start\n```\nOr run the compiled version:\n```bash\nnode dist/main.js\n```\n\n---\n\n## 💡 Bot Usage\n\n1.  Add the bot to your group chat.\n2.  Chat as usual — the bot will save messages in the background.\n3.  To get a summary, mention the bot and specify the desired time interval in natural language:\n    *   `@bot_username summarize the last hour`\n    *   `@bot_username get summary for 3 hours`\n    *   `@bot_username what was discussed today?`\n    *   `@bot_username briefly for yesterday`\n    *   `@bot_username summarization for the last 2 days`\n    *   `@bot_username summarize last 30 minutes` (Russian queries like `суммаризуй за последний час` are also supported)\n\n*Note: If the time period cannot be parsed, the bot defaults to summarizing the last 24 hours.*\n\nIn private chats, send a trigger phrase such as `summarize the last hour` or `суммаризуй за час` to summarize messages visible in that private chat.\n\n## License\n\nMIT. [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyniyniyni%2Ftelegram-summarizer-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyniyniyni%2Ftelegram-summarizer-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyniyniyni%2Ftelegram-summarizer-bot/lists"}