{"id":51090397,"url":"https://github.com/filippolmt/telegram-find-prices","last_synced_at":"2026-06-24T01:30:31.874Z","repository":{"id":337137654,"uuid":"1152461621","full_name":"filippolmt/telegram-find-prices","owner":"filippolmt","description":"Telegram bot that monitors channels for product mentions and price drops. Supports fuzzy matching, target price   alerts, daily summaries, and multi-language (EN/IT). Built with Telethon and SQLAlchemy, deployed via Docker","archived":false,"fork":false,"pushed_at":"2026-03-04T22:12:19.000Z","size":49,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T04:14:27.512Z","etag":null,"topics":["price-tracker","telegram","telegrambot"],"latest_commit_sha":null,"homepage":"","language":"Python","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/filippolmt.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-02-07T22:53:05.000Z","updated_at":"2026-03-04T22:12:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/filippolmt/telegram-find-prices","commit_stats":null,"previous_names":["filippolmt/telegram-find-prices"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/filippolmt/telegram-find-prices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Ftelegram-find-prices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Ftelegram-find-prices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Ftelegram-find-prices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Ftelegram-find-prices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filippolmt","download_url":"https://codeload.github.com/filippolmt/telegram-find-prices/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Ftelegram-find-prices/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34713789,"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-23T02:00:07.161Z","response_time":65,"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":["price-tracker","telegram","telegrambot"],"created_at":"2026-06-24T01:30:31.250Z","updated_at":"2026-06-24T01:30:31.869Z","avatar_url":"https://github.com/filippolmt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Find Prices\n\nTelegram bot that monitors channels and notifies you when a product you're looking for is mentioned, with optional price filtering.\n\n## Features\n\n- `/start` - Register your account\n- `/add_channel` - Add a channel to monitor (public or invite link)\n- `/remove_channel` - Remove a channel from monitoring (keeps the Telegram subscription)\n- `/list_channels` - Show your monitored channels\n- `/watch` - Add a product to monitor (with optional target price and category)\n- `/list_products` - Show your monitored products\n- `/unwatch` - Remove a product from monitoring\n- `/history` - View price history for a product\n- `/pause` - Pause notifications\n- `/resume` - Resume notifications\n- `/stats` - View your statistics\n- `/list_categories` - Show products grouped by category\n- Auto-detects user language (English and Italian supported, English default)\n\n## Prerequisites\n\n- Docker and Docker Compose\n- A Telegram account with:\n  - **API_ID** and **API_HASH** from [my.telegram.org](https://my.telegram.org)\n  - **BOT_TOKEN** from [@BotFather](https://t.me/BotFather)\n  - Your **phone number** associated with the account\n  - Your **numeric user ID** (get it from [@userinfobot](https://t.me/userinfobot))\n\n## Setup\n\n### 1. Clone the repository\n\n```bash\ngit clone \u003crepo-url\u003e\ncd telegram-find-prices\n```\n\n### 2. Configure environment variables\n\n```bash\ncp .env.example .env\n```\n\nFill in `.env` with your credentials:\n\n```\nAPI_ID=123456\nAPI_HASH=abc123def456\nBOT_TOKEN=123456:ABC-DEF\nUSERNAME=your_username\nPHONE_NUMBER=+39123456789\nALLOWED_USERS=12345678\n```\n\n`ALLOWED_USERS` restricts who can use the bot (comma-separated numeric IDs). If empty, the bot is open to everyone.\n\n### 3. First-time authentication\n\nYou have two options:\n\n**Option A: StringSession (recommended for production)**\n\n```bash\nmake gen-session\n```\n\nThis generates a session string that you can store as an environment variable. Telegram sends a verification code to your phone — enter it when prompted. Copy the output and add it to `.env`:\n\n```\nCLIENT_SESSION_STRING=1BVtsO...\n```\n\nNo session files needed. Ideal for containers and CI/CD.\n\n**Option B: File-based session**\n\n```bash\nmake auth\n```\n\nThis creates session files in `data/` that are reused on subsequent runs. Simpler for local development.\n\n### 4. Register bot commands with BotFather\n\nOpen [@BotFather](https://t.me/BotFather), select your bot with `/mybots`, then **Edit Bot** \u003e **Edit Commands** and paste:\n\n```\nstart - Register your account\nadd_channel - Add a channel to monitor\nremove_channel - Remove a channel from monitoring\nlist_channels - Show your monitored channels\nwatch - Add a product to monitor\nlist_products - Show your monitored products\nunwatch - Remove a product from monitoring\nhistory - View price history for a product\npause - Pause notifications\nresume - Resume notifications\nstats - View your statistics\nlist_categories - Show products grouped by category\n```\n\n### 5. Start the bot\n\n```bash\nmake run-d\n```\n\nThe bot starts in the background. Verify it's running with:\n\n```bash\nmake logs\n```\n\nYou should see:\n\n```\n[INFO] Bot started!\n[INFO] Client started!\n[INFO] Channel listener active!\n```\n\n## Make Commands\n\n| Command | Description |\n|---------|-------------|\n| `make auth` | First-time file-based authentication (one-time only) |\n| `make gen-session` | Generate a StringSession for production use |\n| `make run` | Start the bot in foreground |\n| `make run-d` | Start the bot in background |\n| `make logs` | Show bot logs in real-time |\n| `make stop` | Stop the bot |\n| `make test` | Run tests |\n| `make test-v` | Run tests with verbose output |\n| `make test-one T=tests/test_models.py` | Run a single test file |\n| `make shell` | Open a shell inside the container |\n| `make build` | Rebuild the Docker image |\n| `make clean` | Remove containers, images and volumes |\n\n## How it works\n\n1. Add channels to monitor with `/add_channel` (supports public usernames and invite links)\n2. Add products with `/watch` (optionally with a target price and category)\n3. When a message in a monitored channel mentions a product, you receive a notification via bot\n4. If you set a target price, you only get notified when the price found is at or below the target\n5. Fuzzy matching handles hyphens, underscores, and extra spaces in product names\n6. Price history is tracked and a daily summary is sent at a configurable time\n\n## Project structure\n\n```\nsrc/\n  bot.py                      # Entry point\n  auth.py                     # File-based authentication script\n  generate_string_session.py  # StringSession generator for production\n  config.py                   # Configuration from .env\n  database.py                 # SQLAlchemy setup and migrations\n  models.py                   # DB models (User, Channel, Product, PriceHistory)\n  bot_commands.py             # Bot command handlers\n  client_commands.py          # Telegram client operations\n  channel_listener.py         # Channel message listener\n  price_parser.py             # European price format parser\n  scheduler.py                # Daily summary scheduler\n  translations.py             # i18n: message translations (en/it)\ntests/\n  conftest.py                 # Pytest fixtures\n  test_models.py              # DB model tests\n  test_matching.py            # Product matching logic tests\n  test_price_parser.py        # Price parser tests\n  test_translations.py        # Translation tests\nproduction/\n  docker-compose.yml          # Production compose (pre-built ghcr.io image)\n  .env.example                # Production environment template\ndata/                         # Runtime (sessions, database) - gitignored\n```\n\n## Production Deployment\n\nThe Docker image is automatically built and pushed to GitHub Container Registry when a version tag is pushed.\n\n```bash\ncd production\ncp .env.example .env\n# Fill in .env with your credentials and CLIENT_SESSION_STRING\ndocker compose up -d\n```\n\nTo release a new version:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nThe image is tagged with the version (e.g. `1.0.0`) and `latest`. The production compose uses the pre-built image from `ghcr.io/filippolmt/telegram-find-prices:latest`. The `data/` volume persists the SQLite database and session files on the host.\n\nVariables are resolved via Docker Compose interpolation (`${VAR}`): host environment variables take precedence over the `.env` file in the `production/` directory, which takes precedence over defaults defined in the compose file.\n\n## Tests\n\n```bash\nmake test\n```\n\nTests run in an isolated Docker container with an in-memory SQLite database.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippolmt%2Ftelegram-find-prices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilippolmt%2Ftelegram-find-prices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippolmt%2Ftelegram-find-prices/lists"}